@sorenllm/opencode-forge 0.16.0 → 0.17.0

package/README.md

@@ -195,7 +195,7 @@ What this plugin touches, exhaustively:
 | `<tmp>/opencode-forge/jobs/registry.json` | persistent survivor registry (bounded: 100 entries) | runtime debris — after uninstall, kill any still-running `survive` jobs yourself first |
 | `<tmp>/opencode-forge/watchdog/log.jsonl` | watchdog interventions ledger (bounded: 200 entries, oldest rotated) | runtime debris — delete freely, also after uninstall |
 | `<tmp>/opencode-forge/dispatch/ledger.jsonl` | dispatch ledger — **no longer written** (the dispatch engine was removed); only present as inert debris from older versions | runtime debris — delete freely |
-| `.opencode/forge.json` files (the nearest on each host anchor's ancestor chain, every one in an anchor's subtree, and `~/.config/opencode/forge.json`) | your static subagent definitions (JSONC) — pool families MERGED over the global layer per agent id (primary anchor's root pool plain ids, others namespaced). **User data — the plugin only reads them, never writes or migrates them** | yours — version the project ones, keep the global one out of sync tools if it holds machine-specific models |
+| `.opencode/forge.json` (the NEAREST one walking up from the session's worktree — sole ownership) and `~/.config/opencode/forge.json` (global FALLBACK only, never merged) | your static subagent definitions (JSONC) — the workspace pool IS the session's whole roster; nested forge.json files are ignored. **User data — the plugin only reads them, never writes or migrates them** | yours — version the project ones, keep the global one out of sync tools if it holds machine-specific models |
 | `~/.cache/opencode/packages/...` | installed package copy | written by the `opencode plugin` installer, not the plugin |
 | `~/.config/opencode/opencode.json` | `plugin` array entry | written by the installer |
 
@@ -429,58 +429,67 @@ subagent behavior is untouched. Onboarding is this README, for you the human.
 
 ### forge.json — the configuration
 
-A dedicated `forge.json` (JSONC — comments allowed), resolved exactly like
-opencode's own config language — **merged together, not replaced**, project
-discovered by walking up:
-
-1. the project layer: the **nearest** `.opencode/forge.json` walking up from
-   the workspace (session worktree → session directory → host launch
-   directory as the anchor chain; first file found on the ancestor chain
-   wins, nothing above it is consulted)
-2. the global layer: `~/.config/opencode/forge.json`
-
-The two layers **merge**: agents combine, and on an id collision the project
-definition wins wholesale (one definition per id — no cross-layer field
-blending). A broken file empties only its own layer/pool (error finding with
-the parse location); everything else still applies. Both layers re-read at
-every real materialization — host boot, a first config build, or an
-opencode config reload — without a restart; a new session alone does
-not re-read them (see the apply-timing table below).
-
-**Hierarchical pools on a shared host.** Agent frontends (paseo and friends)
-routinely share ONE opencode host process across projects, re-initializing
-plugins with different directories. The plugin therefore keeps an
-**append-only anchor set**: every host initialization appends its directory
-(first one = the *primary anchor*), and pools resolve from the union —
-anchor flips can only ever ADD pools, never remove them. Per anchor the
-family is:
-
-- the **root pool** — the nearest forge.json walking up from that anchor
-  (merged over the global layer per agent id);
-- every **sub-pool** — a `.opencode/forge.json` anywhere in the anchor's
-  subdirectories, discovered by a bounded breadth-first scan (lexicographic
-  sibling order; dependency dirs like `node_modules`/`.git`/`dist` are
-  skipped; 2,000-directory budget per anchor).
-
-The **primary anchor's root pool keeps plain `forge-<id>` ids** (a
-single-project host is unchanged); every other family materializes
-**namespaced** as `forge-<ns>-<id>`. `ns` is the file's optional `pool`
-field, else the sanitized directory name. Pool identity is the absolute file
-path — the same file reached through two anchors materializes exactly once;
-namespace and materialized-id collisions resolve deterministically with an
-error finding, never by silent shadowing. The `/crew` roster and the
-`crew_begin` registration output list the dispatchable agents **grouped by
-pool** with each pool's origin path, the primary marked.
+A dedicated `forge.json` (JSONC — comments allowed) with **workspace pool
+ownership and a global fallback** (sole ownership — the same
+workspace-ownership strictness as opencode's native MCP config):
+
+1. the **workspace pool**: the **nearest** `.opencode/forge.json` walking up
+   from the session's worktree (session worktree → session directory → host
+   launch directory as the anchor chain; first file found on the ancestor
+   chain wins, nothing above it is consulted). When it exists, it **IS the
+   session's whole dispatch roster**.
+2. the **global layer**: `~/.config/opencode/forge.json` — a **fallback
+   ONLY**: when the workspace has no pool file, the global layer serves as
+   the whole roster; when the workspace has one, the global layer is NOT
+   consulted for that session (**a fallback, not a merge** — no per-id
+   blending, global agents never ride a workspace pool).
+
+`forge.json` files nested **deeper** in the workspace's subtree (a cloned
+repo or subfolder carrying its own file) are **ignored entirely** — they
+contribute no agents, split no pools, and extend nothing (a git checkout
+does not change your roster). A broken file empties only its own pool
+(error finding with the parse location); everything else still applies.
+Both layers re-read at every real materialization — host boot, a first
+config build, or an opencode config reload — without a restart; a new
+session alone does not re-read them, and a **deleted pool file
+un-materializes its agents** (deletion is real — no zombie pools).
+
+**Pools on a shared host.** Agent frontends (paseo and friends) routinely
+share ONE opencode host process across projects, re-initializing plugins
+with different directories. The host therefore remembers every workspace
+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.
+
+**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
+host-level); what a given session may actually DISPATCH is scoped
+session-locally: a task call targeting an agent whose pool belongs to
+ANOTHER workspace is refused with a finding naming the target's origin
+pool path, stating it is *not dispatchable from this session*, and the
+exits — open a session in that workspace, or configure the role into this
+workspace's pool / the global layer. The `/crew` roster and the
+`crew_begin` registration output lead with the session's dispatchable pool
+(its forge.json origin — workspace pool, or the global layer marked as
+fallback) and list every other host pool as NOT dispatchable with its
+origin path.
 
 | axis | follows | survives restart? |
 | --- | --- | --- |
-| pools (the `forge-*` vocabulary) | host directories — the anchor set | the set re-seeds from the spawn anchor only |
+| pools (the `forge-*` vocabulary) | workspaces — sole ownership + global fallback | the workspace registry re-seeds from the spawn anchor only |
 | session artifacts (plan/goal/crew records) | the session's own workspace | files on disk are the source of truth |
 
-A forge.json in a directory NO host anchor covers is NOT silently ignored:
-`/crew` names it as the residual mismatch and tells you a host
-initialization in that workspace adds its pools (or fold the agents into the
-global layer).
+A forge.json in a workspace this host has never been initialized in is NOT
+silently ignored: `/crew` names it as the residual mismatch and tells you
+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:
@@ -492,7 +501,7 @@ out of a materialized id.
 
 ```jsonc
 {
-  // sub-pool files only: namespace for this family's ids (forge-<ns>-<id>).
+  // non-primary pool files: namespace for this pool's ids (forge-<ns>-<id>).
   // Short, stable, [a-z0-9-] up to 24 chars — ids survive directory renames.
   // Invalid values degrade to a warning + the directory-derived namespace.
   // "pool": "aa",
@@ -502,8 +511,10 @@ out of a materialized id.
       "model": "zai-coding-plan/glm-5.3", // exact "provider/model" string
       "thoughtLevel": "low",              // none/minimal/low/medium/high/xhigh/max, or any word — write lowercase
       // "prompt": "short role description — explicit prompts fully override the built-ins (only research/review ids have them; any other id without a prompt gets a generic one-liner)",
-      // "shape": "write",   // default readonly denies write/edit/bash + the
-                              // patch family (patch/applypatch/apply/multiedit)
+      // "shape": "readonly", // absent shape defaults to WRITE (open
+                               // permissions); "readonly" is the explicit seal
+                               // denying write/edit/bash + the patch family
+                               // (patch/applypatch/apply/multiedit)
       // "permission": { "bash": "deny" } // optional override; "task" is ALWAYS denied
     },
     // AUTO worker: set NEITHER — inherits the parent session's model at
@@ -546,13 +557,18 @@ A rejected entry costs only itself — its siblings materialize normally.
   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
+   and a deny-style permission: an ABSENT `shape` defaults to WRITE (open
+   permissions — the compatibility-preserving default for existing pools);
+   an explicit `shape: "readonly"` denies
    the full mutating-tool family — `write`/`edit`/`bash` plus the host's
    patch family (`patch`/`applypatch`/`apply`/`multiedit`) — `shape:
-   "write"` allows them, an explicit `permission` map overrides the shape
+   "write"` allows them (same as absent), an explicit `permission` map overrides the shape
    default (lifting ANY member of that family off `deny` forfeits the
    draft-phase readonly exemption) — and `task` is ALWAYS
-   denied (recursive spawning stays physically impossible).
+   denied (recursive spawning stays physically impossible). Readonly is a
+   restriction you ask for explicitly, never a surprise default — new pools
+   should give every agent an explicit `shape` (the `/crew` initialization
+   gate teaches the AI author exactly this).
 
 > **Upgrading from ≤ 0.5.0 (breaking):** agent entries that pinned `model`
 > without `thoughtLevel` used to be accepted; they are now SKIPPED with an
@@ -560,17 +576,17 @@ A rejected entry costs only itself — its siblings materialize normally.
 > `thoughtLevel`, or delete `model` to make it an Auto worker.
 
 **What applies when** — only a real materialization re-reads the pool
-files into the `forge-*` vocabulary; the anchor set itself only ever grows.
-Materialization triggers (2026-10-01 live finding): host boot (a freshly
-started CLI process reads the files as they are), the FIRST config build
-for a directory on this host, and opencode config file reloads. A NEW
-session on a long-lived shared host (serve-type) does NOT re-materialize:
+files into the `forge-*` vocabulary. Materialization triggers (2026-10-01
+live finding): host boot (a freshly started CLI process reads the files as
+they are), the FIRST config build for a directory on this host, and
+opencode config file reloads. A NEW session on a long-lived shared host
+(serve-type) does NOT re-materialize:
 
 | change | needs a host restart? |
 | --- | --- |
 | `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 and depth lookups resolve the pool files fresh regardless |
-| 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 appends the anchor and its pools (append-only; existing pools never flip) |
+| 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) |
 
 ### Dispatching
 
@@ -589,6 +605,50 @@ providers can return a deterministic EMPTY response for any toolset-reduced
 attributable task failure; the mitigation is unchanged — use
 `shape: "write"` for such endpoints, or a keyed provider.
 
+### Readonly exec seal (the sealed supervised-exec channel)
+
+The readonly shape used to seal only the TOOL face (write/edit/bash + the
+patch family) — a readonly worker could still mutate the world through its
+exec channel (`forge_shell`). The exec seal closes that hole: a session whose
+running `forge-*` worker has an **explicit** `shape: "readonly"` (an absent
+shape defaults to write and is **never** sealed) has its `forge_shell` calls
+classified BEFORE spawn by a pure string classifier (`src/exec-classify.ts`,
+no fs access at classify time). READ-CLASS commands (inspection, search,
+read-only evals — `rg`, `git log`/`status`/`diff`, `node -e`/`python -c`
+read evals, version/help queries) flow normally; **WRITE-CLASS commands are
+denied** with a bounded finding (once per session per indicator class) that
+names the readonly shape, names the classified write indicator, and points
+at the remedy: `"shape": "write"` on that agent when its job legitimately
+mutates. The worker is told to report the refusal verbatim, not work around
+it. The primary forge session is never sealed; a session whose agent cannot
+be resolved fails open (one-time disclosure). The seal composes with — never
+replaces — the draft-phase ask/deny posture on the channel.
+
+Covered WRITE-CLASS indicators:
+
+| indicator | covers |
+| --- | --- |
+| `redirect` | output redirection to files — `>` `>>` and fd forms (`2>`, `1>`, `*>`); the PowerShell family uses the same operators |
+| `mutating-cmdlet` | `Set-Content`, `Out-File`, `New-Item`, `Remove-Item`, `Move-Item`, `Copy-Item`, `Add-Content`, `Clear-Content` |
+| `git-mutation` | `git add/commit/push/reset/checkout/rebase/merge/clean/rm` |
+| `pkg-mutation` | `npm publish`, `npm install` (incl. `npm i`/`ci`/`add`), `bun add`/`install`, `pip`/`pip3 install` |
+| `workspace-write` | output-target flags (`--out`, `--output`, `--out-file`/`--outfile`/`--outFile`, `--dest`, `--destination`, `-o`) whose parsed value is a workspace-relative path, or an absolute path under the session workspace |
+
+**Honest positioning — this is belt-in-depth, NOT a sandbox.** A command
+that fails to classify is treated as READ-CLASS (fail-open on the channel,
+the same posture as every refusal belt). The known bypass surface, verbatim:
+**indirect writes** (a script that writes internally — `node build.js` with
+no redirect is indirection the classifier does not model), **`Start-Process`
+writers** (spawning a writer process is explicitly out of scope), and
+**encoded payloads** (`powershell -EncodedPayload …`, base64 blobs) are NOT
+covered; they flow on the readonly channel. The seal narrows the exec hole
+from "completely open" to "explicitly constructed indirection" — a true OS
+level seal (write-time redirection, shadow copies, containers, win32+POSIX
+dual implementations) was evaluated and rejected as a disproportionate
+rewrite (see `openspec/changes/readonly-exec-seal/design.md`, option D3).
+The tool-face deny remains the first belt; this is the second.
+
+
 ### The thoughtLevel word
 
 One word per agent: the canonical seven-word dictionary
@@ -721,18 +781,23 @@ itself (a rootish guard keeps degenerate global-project worktrees from
 landing files on the drive root or the launch anchor). The anchor follows the
 session's workspace, never the objective's scope.
 
-**Not initialized?** `/crew` on a host with ZERO pools across its whole
-anchor set refuses with one-time setup guidance: the two file paths, a
-copy-paste template, and the choice of configuring it yourself OR having the
-session AI do it — the latter only on your explicit go-ahead in that
-conversation, through the normal visible write path (when the AI writes a
-sub-pool file it also proposes a short stable `pool` namespace so ids
-survive directory renames). This is the plugin's only configuration
-invitation. Saved files apply at the next real materialization — no
-restart needed; on a shared host, the first session in a NEW workspace adds
-that anchor and its pools automatically (a new session in an existing
-workspace does not re-read the files — see the apply-timing table
-above).
+**Not initialized?** `/crew` on a session whose roster is EMPTY (neither
+its workspace pool nor the global fallback materializes an agent) refuses
+with one-time setup guidance: the two file paths and their sole-ownership
+relationship (the workspace pool IS the whole roster; the global layer is
+fallback-only, never merged; nested forge.json files ignored), a
+copy-paste template, and the choice of configuring it yourself OR having
+the session AI do it — the latter only on your explicit go-ahead in that
+conversation, through the normal visible write path (when the AI writes
+the file every agent gets an explicit `shape` — `readonly` for read-only
+roles, `write` for implementers — and it also proposes a short stable
+`pool` namespace so ids survive directory renames). This is the plugin's
+only configuration invitation. Saved files apply at the next real
+materialization — no restart needed, and a deleted pool file
+un-materializes its agents; on a shared host, the first session in a NEW
+workspace registers that workspace and its pool automatically (a new
+session in an existing workspace does not re-read the files — see the
+apply-timing table above).
 
 ### Debris note
 
@@ -812,16 +877,20 @@ The escape hatches are `plan_approve` and `/plan discard`, by design.
 
 One carve-out, keyed on the target rather than the tool: during a draft the
 `task` tool is gated by the dispatch target's **effective readonly shape**. A
-dispatch to a forge worker whose shape is not `write` AND whose permission
+dispatch to a forge worker whose shape is EXPLICITLY `readonly` AND whose
+permission
 overrides do not lift `write`/`edit`/`bash` — nor any host patch-family tool
 (`patch`/`applypatch`/`apply`/`multiedit`) — off `deny` (`ask` counts as
 lifted — fail-closed) passes as a reconnaissance dispatch: readonly scouts
 may be spawned both before and during the draft, so breadth
-evidence-gathering does not burn the planning session's context. Every other
-target — write-shaped workers, native agents, absent or unresolvable targets
+evidence-gathering does not burn the planning session's context. A worker
+with NO shape field is not exempt (absent defaults to write). Every other
+target — write-shaped and shape-less workers, native agents, absent or
+unresolvable targets
 (including resume calls that carry no target) — is denied like any write-class
 tool. The refusal names the currently dispatchable effective-readonly roster,
-points to defining a readonly worker in forge.json when the roster is empty
+points to defining a readonly worker in forge.json (explicit
+`"shape": "readonly"`) when the roster is empty
 (an unconfigured host stays fully denied — same behavior as before, just more
 actionable wording), and names the two exits (`plan_approve`, `/plan
 discard`). Invariant strength is unchanged: the scout's materialized

package/dist/index.js

@@ -12335,7 +12335,7 @@ function tool(input) {
 tool.schema = exports_external;
 // plugin.ts
 import { execFileSync as execFileSync3 } from "node:child_process";
-import { appendFileSync, existsSync as existsSync3, mkdirSync as mkdirSync5, readdirSync as readdirSync5, readFileSync as readFileSync8, realpathSync, statSync as statSync5, writeFileSync as writeFileSync5 } from "node:fs";
+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 { tmpdir as tmpdir3, homedir } from "node:os";
 
@@ -15053,13 +15053,13 @@ function rolePromptFor(agentId, def) {
   return ROLE_PROMPTS[agentId] ?? `You are a ${agentId} worker. Execute the assigned task exactly as scoped.`;
 }
 function agentDescriptionFor(agentId, def) {
-  const shape = def.shape === "write" ? "write" : "readonly";
+  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}".`;
 }
 function forgeAgentDef(agentId, def) {
   const permission = { task: "deny" };
-  const shape = def.shape ?? "readonly";
+  const shape = def.shape ?? "write";
   if (shape === "readonly") {
     for (const t of MUTATING_TOOLS)
       permission[t] = "deny";
@@ -15082,7 +15082,7 @@ function forgeAgentDef(agentId, def) {
   return entry;
 }
 function effectiveReadonlyShape(def) {
-  if (def.shape === "write")
+  if (def.shape !== "readonly")
     return false;
   const perm = def.permission ?? {};
   for (const t of MUTATING_TOOLS) {
@@ -15093,6 +15093,165 @@ function effectiveReadonlyShape(def) {
   return true;
 }
 
+// src/exec-classify.ts
+var READ_CLASS = "READ";
+var WRITE_CLASS = "WRITE";
+var REDIRECT_INDICATOR = "redirect";
+var MUTATING_CMDLETS = [
+  "Set-Content",
+  "Out-File",
+  "New-Item",
+  "Remove-Item",
+  "Move-Item",
+  "Copy-Item",
+  "Add-Content",
+  "Clear-Content"
+];
+var GIT_MUTATING_SUBCOMMANDS = [
+  "add",
+  "commit",
+  "push",
+  "reset",
+  "checkout",
+  "rebase",
+  "merge",
+  "clean",
+  "rm"
+];
+var PKG_MUTATING_COMMANDS = ["npm publish", "npm install", "bun add", "pip install"];
+var PKG_MUTATING_PATTERNS = [
+  /\bnpm\s+(?:publish|install|i|ci|add)\b/i,
+  /\bbun\s+(?:add|install)\b/i,
+  /\bpip3?\s+install\b/i
+];
+var WRITE_TARGET_FLAGS = [
+  "--out",
+  "--output",
+  "--out-file",
+  "--outfile",
+  "--outFile",
+  "--dest",
+  "--destination",
+  "-o"
+];
+var EXEC_SEAL_INDICATORS = [
+  { id: REDIRECT_INDICATOR, covers: "`>` `>>` and fd forms (`2>` `*>`) — bash and the PowerShell family share the operators" },
+  { id: "mutating-cmdlet", covers: MUTATING_CMDLETS.join(", ") },
+  { id: "git-mutation", covers: `git ${GIT_MUTATING_SUBCOMMANDS.join("/")}` },
+  { id: "pkg-mutation", covers: PKG_MUTATING_COMMANDS.join(", ") + " (with common aliases: npm i/ci/add, bun install, pip3 install)" },
+  { id: "workspace-write", covers: `output-target flags ${WRITE_TARGET_FLAGS.join(" ")} whose parsed value is a workspace-relative path (or an absolute path under the provided workspaceRoot)` }
+];
+function stripQuoted(cmd) {
+  let out = "";
+  let quote = null;
+  for (const ch of cmd) {
+    if (quote) {
+      if (ch === quote)
+        quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    out += ch;
+  }
+  return out;
+}
+function redirectMatch(cmd) {
+  const bare = stripQuoted(cmd).replace(/\r?\n/g, " ");
+  const m = /(?:^|[^>&])>{1,2}(?!&)[^\s;&|]*/.exec(bare);
+  if (m)
+    return { detail: m[0].trim() };
+  return null;
+}
+function wordMatch(cmd, needle) {
+  const re = new RegExp(`(^|[\\s;&|(])${needle.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i");
+  const m = re.exec(cmd);
+  if (m)
+    return { detail: m[0].trim() };
+  return null;
+}
+function gitMutationMatch(cmd) {
+  const bare = stripQuoted(cmd);
+  for (const sub of GIT_MUTATING_SUBCOMMANDS) {
+    const m = new RegExp(`(?:^|[\\s;&|(])git\\s+${sub}\\b`, "i").exec(bare);
+    if (m)
+      return { detail: m[0].trim() };
+  }
+  return null;
+}
+function pkgMutationMatch(cmd) {
+  const bare = stripQuoted(cmd);
+  for (const re of PKG_MUTATING_PATTERNS) {
+    const m = re.exec(bare);
+    if (m)
+      return { detail: m[0].trim() };
+  }
+  return null;
+}
+function isDriveRelative(p) {
+  return /^[a-zA-Z]:/.test(p);
+}
+function pathLike(p) {
+  return /^[^;&|<>]+$/.test(p) && /[./\\]/.test(p);
+}
+function insideWorkspace(value, workspaceRoot) {
+  const norm = (s) => s.replaceAll("\\", "/").replace(/\/+$/, "").toLowerCase();
+  if (!isDriveRelative(value) && !value.startsWith("/") && !value.startsWith("\\\\")) {
+    return true;
+  }
+  if (workspaceRoot === undefined)
+    return false;
+  return norm(value).startsWith(`${norm(workspaceRoot)}/`) || norm(value) === norm(workspaceRoot);
+}
+function workspaceWriteMatch(cmd, workspaceRoot) {
+  const tokens = stripQuoted(cmd).split(/\s+/).filter(Boolean);
+  for (let i = 0;i < tokens.length; i++) {
+    const tok = tokens[i];
+    let flag = "";
+    let value;
+    const eq = tok.indexOf("=");
+    if (eq > 0 && tok.startsWith("--")) {
+      flag = tok.slice(0, eq);
+      value = tok.slice(eq + 1);
+    } else if (WRITE_TARGET_FLAGS.includes(tok)) {
+      flag = tok;
+      value = tokens[i + 1];
+    }
+    if (!flag || value === undefined)
+      continue;
+    if (value.startsWith("-"))
+      continue;
+    if (pathLike(value) && insideWorkspace(value, workspaceRoot)) {
+      return { detail: `${flag} ${value}` };
+    }
+  }
+  return null;
+}
+function classifyExecCommand(cmd, opts) {
+  if (typeof cmd !== "string" || cmd.length === 0)
+    return { klass: READ_CLASS };
+  const r = redirectMatch(cmd);
+  if (r)
+    return { klass: WRITE_CLASS, indicator: REDIRECT_INDICATOR, detail: r.detail };
+  for (const cmdlet of MUTATING_CMDLETS) {
+    const m = wordMatch(cmd, cmdlet);
+    if (m)
+      return { klass: WRITE_CLASS, indicator: "mutating-cmdlet", detail: m.detail };
+  }
+  const g = gitMutationMatch(cmd);
+  if (g)
+    return { klass: WRITE_CLASS, indicator: "git-mutation", detail: g.detail };
+  const p = pkgMutationMatch(cmd);
+  if (p)
+    return { klass: WRITE_CLASS, indicator: "pkg-mutation", detail: p.detail };
+  const w = workspaceWriteMatch(cmd, opts?.workspaceRoot);
+  if (w)
+    return { klass: WRITE_CLASS, indicator: "workspace-write", detail: w.detail };
+  return { klass: READ_CLASS };
+}
+
 // src/dispatch-depth.ts
 var META_DEPTHS = ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
 var BUDGET_TIERS = {
@@ -15176,7 +15335,7 @@ function resolvePinnedDepth(thoughtLevel, channel) {
 }
 
 // src/forge-config.ts
-import { readdirSync as readdirSync4, readFileSync as readFileSync7, statSync as statSync4 } from "node:fs";
+import { readFileSync as readFileSync7, statSync as statSync4 } from "node:fs";
 function sanitizeJsonc(text) {
   const out = [];
   let i = 0;
@@ -15630,8 +15789,6 @@ function createForgeConfigLoader(deps) {
     }
   };
 }
-var POOL_SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "out", "target", ".cache", "venv", ".venv", "__pycache__", "coverage"]);
-var POOL_SCAN_BUDGET = 2000;
 function sanitizeNamespace(name) {
   const collapsed = name.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
   return collapsed || "pool";
@@ -15664,14 +15821,6 @@ function createPoolResolver(deps) {
     }
   });
   const readFile = deps.readFile ?? ((path) => readFileSync7(path, "utf8"));
-  const readdir = deps.readdir ?? ((dir) => {
-    try {
-      return readdirSync4(dir, { withFileTypes: true }).map((d) => ({ name: d.name, dir: d.isDirectory() }));
-    } catch {
-      return null;
-    }
-  });
-  const budget = typeof deps.scanBudget === "number" && deps.scanBudget > 0 ? deps.scanBudget : POOL_SCAN_BUDGET;
   const globalPath = forgeConfigPaths({ homeDir: deps.homeDir }).global;
   const fileCache = new Map;
   const readPool = (path) => {
@@ -15708,56 +15857,14 @@ function createPoolResolver(deps) {
     fileCache.set(path, { mtimeMs: st.mtimeMs, size: st.size, parsed });
     return parsed;
   };
-  const dirCache = new Map;
-  const listDir = (dir) => {
-    const st = stat(dir);
-    if (st === null) {
-      dirCache.delete(dir);
+  const workspacePoolOf = (anchor) => {
+    const dir = (anchor ?? "").trim();
+    if (!dir)
       return null;
-    }
-    const hit = dirCache.get(dir);
-    if (hit && hit.mtimeMs === st.mtimeMs)
-      return hit;
-    const listing = readdir(dir);
-    const children = listing === null ? null : [...listing].sort((a, b) => codepointCompare(a.name, b.name));
-    let poolFile = null;
-    const candidate = forgeCandidateAt(dir);
-    if (stat(candidate) !== null)
-      poolFile = candidate;
-    const entry = { mtimeMs: st.mtimeMs, children, poolFile };
-    dirCache.set(dir, entry);
-    return entry;
-  };
-  const scanSubtree = (anchor) => {
-    const files = [];
-    const seen = new Set;
-    let opened = 0;
-    const sep2 = anchor.includes("\\") && !anchor.includes("/") ? "\\" : "/";
-    const joinDir = (parent, name) => parent.endsWith("/") || parent.endsWith("\\") ? `${parent}${name}` : `${parent}${sep2}${name}`;
-    const queue = [anchor];
-    while (queue.length > 0 && opened < budget) {
-      const dir = queue.shift();
-      if (seen.has(dir))
-        continue;
-      seen.add(dir);
-      const entry = listDir(dir);
-      opened++;
-      if (entry === null || entry.children === null)
-        continue;
-      const isAnchor = dir === anchor;
-      if (!isAnchor && entry.poolFile !== null)
-        files.push(entry.poolFile);
-      for (const child of entry.children) {
-        if (!child.dir)
-          continue;
-        if (POOL_SKIP_DIRS.has(child.name) || child.name === ".opencode")
-          continue;
-        queue.push(joinDir(dir, child.name));
-      }
-    }
-    return files;
+    return discoverProjectFileWith(stat, dir);
   };
   return {
+    workspacePoolOf,
     resolve(anchorsInput) {
       const anchors = [];
       for (const a of anchorsInput) {
@@ -15769,20 +15876,17 @@ function createPoolResolver(deps) {
       const globalParsed = globalPath ? readPool(globalPath) : null;
       if (globalParsed)
         findings.push(...globalParsed.findings);
-      const primaryRootFile = anchors.length > 0 ? discoverProjectFileWith(stat, anchors[0]) : null;
       const uniqueFiles = new Set;
-      if (primaryRootFile)
-        uniqueFiles.add(primaryRootFile);
       for (const anchor of anchors) {
-        for (const f of scanSubtree(anchor))
+        const f = workspacePoolOf(anchor);
+        if (f)
           uniqueFiles.add(f);
-        if (anchor !== anchors[0]) {
-          const rootFile = discoverProjectFileWith(stat, anchor);
-          if (rootFile)
-            uniqueFiles.add(rootFile);
-        }
       }
-      const plainPoolFile = primaryRootFile ?? (globalParsed !== null && globalPath ? globalPath : null);
+      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 families = [];
       for (const file2 of orderedFiles) {
@@ -15811,7 +15915,7 @@ function createPoolResolver(deps) {
       for (const f of families) {
         if (f.primary)
           continue;
-        const base = f.declaredPool ?? sanitizeNamespace(dirBasename(parentDirLabel(parentDirLabel(f.file))));
+        const base = f.declaredPool ?? (f.file === globalPath ? "global" : sanitizeNamespace(dirBasename(parentDirLabel(parentDirLabel(f.file)))));
         let ns = base;
         let suffix = 2;
         while ((usedNs.has(ns) || ns !== base && allDeclared.has(ns)) && suffix < 100) {
@@ -15827,16 +15931,16 @@ function createPoolResolver(deps) {
       const agents = {};
       const origins = [];
       for (const f of families) {
-        const merged = { ...globalParsed?.agents ?? {}, ...f.parsed?.agents ?? {} };
+        const own = f.parsed?.agents ?? {};
         const ids = [];
-        for (const rawId of Object.keys(merged)) {
+        for (const rawId of Object.keys(own)) {
           const matId = f.ns === null ? rawId : `${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` });
             continue;
           }
-          agents[matId] = { materializedId: matId, def: merged[rawId], ns: f.ns, file: f.file };
+          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 });
@@ -15948,6 +16052,8 @@ function effectiveWorktree(worktree, fallback) {
 }
 var sessions = new Map;
 var sessionAgents = new Map;
+var sealFindings = new Map;
+var sealUnknownNotes = new Set;
 function isForgeFamilyAgent(name) {
   if (typeof name !== "string")
     return false;
@@ -15968,6 +16074,11 @@ var forgeDisabled = false;
 var hostAnchors = [];
 var poolResolver = null;
 var poolResolution = null;
+var poolGateUnknownNotes = new Set;
+var foldPath = (p) => process.platform === "win32" ? p.replace(/\//g, "\\").toLowerCase() : p;
+function globalPoolPathOf() {
+  return forgeConfigPaths({ homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() }).global;
+}
 function normalizeAnchorDir(dir) {
   let p = (dir ?? "").trim();
   if (!p)
@@ -15999,7 +16110,7 @@ function loaderForAnchor(anchor) {
   const key = anchor || "-";
   let l = sessionAnchorLoaders.get(key);
   if (!l) {
-    l = createForgeConfigLoader({ projectDir: anchor, homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() });
+    l = createForgeConfigLoader({ projectDir: anchor });
     sessionAnchorLoaders.set(key, l);
     while (sessionAnchorLoaders.size > 8) {
       const oldest = sessionAnchorLoaders.keys().next().value;
@@ -16010,6 +16121,11 @@ function loaderForAnchor(anchor) {
   }
   return l;
 }
+function sessionPoolFileOf(anchor) {
+  if (poolResolver)
+    return poolResolver.workspacePoolOf(anchor);
+  return loaderForAnchor(anchor).load().projectPath;
+}
 var crews = new Map;
 function crewRecordPathFor(worktree, objective) {
   const dir = join6(worktree, ".opencode", "crew");
@@ -16231,7 +16347,7 @@ function readPlanDir(worktree) {
   const dir = planDirOf(worktree);
   if (!existsSync3(dir))
     return [];
-  return readdirSync5(dir).filter((f) => f.endsWith(".md")).map((name) => ({ name, text: readFileSync8(join6(dir, name), "utf8") }));
+  return readdirSync4(dir).filter((f) => f.endsWith(".md")).map((name) => ({ name, text: readFileSync8(join6(dir, name), "utf8") }));
 }
 function ensureSession(sessionID, worktree) {
   const existing = sessions.get(sessionID);
@@ -16298,7 +16414,7 @@ var planWriteTool = tool({
     } else {
       const dir = planDirOf(state.worktree);
       mkdirSync5(dir, { recursive: true });
-      path = join6(dir, planFileName(localDate(), slugify(args.goal), readdirSync5(dir).filter((f) => f.endsWith(".md"))));
+      path = join6(dir, planFileName(localDate(), slugify(args.goal), readdirSync4(dir).filter((f) => f.endsWith(".md"))));
       mode = "created";
     }
     const text = renderPlan(args, now, created);
@@ -16434,7 +16550,7 @@ function readGoalDir(worktree) {
   const dir = goalDirOf(worktree);
   if (!existsSync3(dir))
     return [];
-  return readdirSync5(dir).filter((f) => f.endsWith(".md")).map((name) => ({ name, text: readFileSync8(join6(dir, name), "utf8") }));
+  return readdirSync4(dir).filter((f) => f.endsWith(".md")).map((name) => ({ name, text: readFileSync8(join6(dir, name), "utf8") }));
 }
 function resolveSessionGoal(state) {
   if (state.goalPath && existsSync3(state.goalPath)) {
@@ -16543,7 +16659,7 @@ var goalWriteTool = tool({
     }
     const dir = goalDirOf(state.worktree);
     mkdirSync5(dir, { recursive: true });
-    const name = goalFileName(localDateNow(), slugifyGoal(args.goal), readdirSync5(dir).filter((f) => f.endsWith(".md")));
+    const name = goalFileName(localDateNow(), slugifyGoal(args.goal), readdirSync4(dir).filter((f) => f.endsWith(".md")));
     const path = join6(dir, name);
     const text = renderGoal(input, {
       now,
@@ -16915,44 +17031,48 @@ var CREW_INIT_TEMPLATE = [
   "",
   "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 materialized across the whole host anchor set (zero pools). Refuse to enter orchestration and tell the user this feature needs a one-time setup, offering BOTH options:",
+  "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). 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 either layer — MERGED, the project layer overrides the global one per agent id (the project file is the nearest .opencode/forge.json walking up from the workspace root; a .opencode/forge.json in any anchor subdirectory additionally forms a namespaced sub-pool family, its ids materializing as forge-<ns>-<id>):",
+  "1. The user configures it themselves — create either layer, SOLE OWNERSHIP (the same workspace-ownership strictness as opencode's native MCP config): the workspace pool is the NEAREST .opencode/forge.json walking up from this session's worktree, and when it exists it IS the session's whole roster; the global layer serves only as the fallback when the workspace has none — a fallback, NOT a merge (a workspace with a pool never sees global agents; nested forge.json files deeper in the workspace subtree are ignored entirely):",
   "{paths}",
   "",
-  "Two axes, distinct: POOLS follow host directories (the host's anchor set); SESSION ARTIFACTS (plan/goal/crew records) follow the session. A forge.json in a directory no host anchor covers is not dispatchable on this host.",
+  "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. For sub-pool files, ALSO include a proposed short stable `pool` namespace (a [a-z0-9-] word up to 24 chars — e.g. "aa" for a devAa 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 — 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.',
   "",
-  "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 top level: `pool` — the file's namespace.",
+  "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}",
   "",
-  "After the file is saved: file edits, creations, and deletions apply at the next config hook — NO host restart is needed. Only the anchor set itself is fixed at host start: host re-initializations add anchors and pools, they never remove them."
+  "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)."
 ].join(`
 `);
 function crewOrchestrationTemplate(resolution) {
   const families = resolution?.families ?? [];
-  const familyLines = families.map((f) => {
-    const label = f.primary ? "root pool (PRIMARY, plain ids)" : `pool ${f.ns} (forge-${f.ns}-*)`;
-    return `  - ${label}: ${f.file} — ${f.materializedIds.map((id) => `forge-${id}`).join(", ") || "no agents"}`;
+  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}-*)`;
+    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 [
     '(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), grouped by pool:",
-    ...familyLines.length > 0 ? familyLines : ["  (none)"],
+    "Configured forge subagents (task-tool vocabulary). ROSTER OWNERSHIP (sole ownership): THIS session's dispatchable roster is its WORKSPACE pool — the nearest .opencode/forge.json walking up from this session's worktree — or, when the workspace has none, the GLOBAL fallback layer (a fallback, not a merge; forge.json files nested deeper in the workspace subtree are ignored, same as opencode's native MCP config). Check this workspace's pool:",
+    '  - this workspace pool (when the path prints, its agents ARE the roster): !`ls .opencode/forge.json 2>/dev/null || echo "(no workspace pool — the global fallback applies)"`',
+    `  - global fallback layer: ${globalPath} — dispatchable ONLY when the workspace has no pool of its own`,
+    ...otherLines.length > 0 ? ["Other pools materialized on this host — each NOT dispatchable from this session (open a session in that workspace, or configure the role into this workspace's pool / the global layer):", ...otherLines] : [],
     "",
     "You are entering CREW ORCHESTRATION discipline for this session (single subject: do not switch agents). The macro contract above the crew may come from an approved plan, a spec change, or inline text — the discipline is identical in all three cases and never requires a plan. Follow it exactly:",
     "",
     '1. REGISTER: call `crew_begin` with the objective AND the declared subtask plan (subtasks[]: one {title} per subtask, optionally naming the intended forge-* agent). When the macro contract descends from a plan artifact, pass its path as the optional `lineage` argument (e.g. lineage: ".opencode/plan/2026-10-01-my-plan.md") — the descent is recorded as a first-class line in the crew record header; lineage is never inferred. Reconnaissance BEFORE registration is free (task calls included). If crew_begin refuses (a crew is already active here, or a plan draft is active), STOP and tell the user why — never start a second crew. A wrong plan is fixed by abandoning and re-crewing (crew_close {abandon: true, reason}), never by improvising outside the declared plan.',
     `2. THE PAUSE: registration enters a PENDING crew — execution has NOT started. STOP and present the user the three execution-mode choices (supervised waves now / convert to a goal contract / standby), then END YOUR TURN. Arm per the user's choice: waves → crew_begin {execution: "waves"}; conversion → crew_begin {execution: "goal"} followed by goal_write (arm=true — its dialog is the user's gate) folding the declared subtasks into criteria/checks; standby → no call. EXCEPTION: while a live active goal governs this session, register with execution: "waves" in the SAME call — the crew is born armed (the goal contract already authorized orchestration) and crew_close / abandon stay ask-free under that goal.`,
     "3. WAVES, NEVER FLOODS (armed crews only): execute subtasks in waves of parallel native `task` calls (subagent_type = the matching forge-* agent; a wave's results return within the calling turn). Launch the next wave ONLY after the previous wave's results are in. GUI / computer-use subtasks are mutually exclusive within a wave (the desktop is a singleton resource — at most ONE in flight; non-GUI subtasks still parallelize freely), and GUI walkthroughs use the `computer` tool rather than DIY shell screenshot pipelines.",
-    "4. MISSING ROLE: when a subtask needs a role no configured forge-* agent matches, run that subtask through a native task call anyway AND tell the user about the gap — suggest configuring the missing role in forge.json.",
-    "5. VERIFY: judge each subtask strictly against its acceptance-evidence statement from the task result text. A result that does not meet the statement is a failure even if the worker sounded confident.",
-    "6. RETRY AT MOST ONCE: a failed subtask may be retried once with an adjusted prompt or agent. If the retry also fails, record the subtask as FAIL with BOTH failure reports visible (attempts[]). Do not retry twice, do not paper over a failure.",
-    "7. CLOSE: when every declared subtask has a verdict, call `crew_close` with the full report (title/verdict/evidence per subtask; attempts[] for FAILs). The gate cross-checks the report against the declared plan — a declared subtask missing from the report refuses the close, and so does an undeclared one. The user confirms the closing dialog (ask-free while a goal governs the session)."
+    "4. CONTRACT RELAY (lineage-descended crews): when the macro contract descends from an on-disk artifact (the lineage names a plan artifact, a spec change directory, or a goal contract), every subtask's dispatch prompt MUST explicitly carry that artifact's path — or the exact slice the subtask works from (a delta file path, a quoted criteria section) — so the dispatched worker reads the contract itself, never your paraphrase of it. A large artifact is relayed by its exact slice; it is NEVER dropped for being too long to inline. Every close-report evidence statement MUST name the contract (or slice) the subtask worked against.",
+    "5. MISSING ROLE: when a subtask needs a role no configured forge-* agent matches, run that subtask through a native task call anyway AND tell the user about the gap — suggest configuring the missing role in forge.json.",
+    "6. VERIFY: judge each subtask strictly against its acceptance-evidence statement from the task result text. A result that does not meet the statement is a failure even if the worker sounded confident.",
+    "7. RETRY AT MOST ONCE: a failed subtask may be retried once with an adjusted prompt or agent. If the retry also fails, record the subtask as FAIL with BOTH failure reports visible (attempts[]). Do not retry twice, do not paper over a failure.",
+    "8. CLOSE: when every declared subtask has a verdict, call `crew_close` with the full report (title/verdict/evidence per subtask; attempts[] for FAILs). The gate cross-checks the report against the declared plan — a declared subtask missing from the report refuses the close, and so does an undeclared one. The user confirms the closing dialog (ask-free while a goal governs the session)."
   ].join(`
 `);
 }
@@ -16975,26 +17095,28 @@ var crewBeginTool = tool({
       throw new Error("[forge:crew] A plan is in draft; crew orchestration is denied during planning. Three exits: " + "plan_approve puts the plan to user approval (an APPROVED plan does not block /crew — only a draft does); " + "/plan discard abandons the plan outright; " + '/plan discard {supersede: "<successor path or id>"} moves the work into this crew (the plan becomes superseded, the successor recorded).');
     }
     const resolution = resolvePools();
-    const hostIds = resolution ? Object.keys(resolution.agents) : [];
     const anchor = sessionAnchor(context);
+    if (anchor)
+      ensureSession(context.sessionID, anchor);
     const sessionLoaded = anchor ? loaderForAnchor(anchor).load() : null;
     const sessionProject = sessionLoaded?.projectPath ?? null;
-    const foldPath = (p) => process.platform === "win32" ? p.replace(/\//g, "\\").toLowerCase() : p;
-    const sessionCovered = sessionProject === null || (resolution?.families.some((f) => foldPath(f.file) === foldPath(sessionProject)) ?? false);
-    if (hostIds.length === 0) {
-      const primaryAnchorDir = hostAnchors[0] ?? hostWorktree;
-      const anchorNote = hostAnchors.length > 1 ? `host anchors: ${hostAnchors.join(", ")}` : `launched from ${primaryAnchorDir || "an unresolvable directory"}`;
-      const paths = forgeConfigPaths({ projectDir: primaryAnchorDir || undefined, homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() });
+    const globalPoolPath = forgeConfigPaths({ homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() }).global;
+    const sessionPool = sessionProject;
+    const sessionFamily = resolution?.families.find((f) => foldPath(f.file) === foldPath(sessionPool ?? globalPoolPath)) ?? null;
+    const sessionCovered = sessionPool === null || sessionFamily !== null;
+    const sessionRosterIds = sessionFamily ? sessionFamily.materializedIds : [];
+    if (sessionRosterIds.length === 0) {
+      const paths = forgeConfigPaths({ projectDir: anchor || undefined, homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() });
       const lines2 = [
-        `[forge:crew] CREW IS NOT INITIALIZED on this host: no forge subagents are materialized across the whole anchor set (${anchorNote}). Crew orchestration is unavailable until the user sets it up.`,
-        `Two layers, MERGED (the project layer overrides the global one per agent id): ${paths.project} (nearest .opencode/forge.json walking up from the workspace) OR ${paths.global}. Sub-pool files (.opencode/forge.json in an anchor's subdirectories) contribute additional namespaced families.`,
-        "Two axes, distinct: POOLS follow host directories (the anchor set above); SESSION ARTIFACTS (plan/goal/crew records) follow the session. A forge.json in an unanchored directory is not dispatchable on this host.",
-        `Template (JSONC): top-level optional "pool" names this file's namespace (short stable [a-z0-9-] up to 24 chars — sub-pool ids materialize as forge-<ns>-<id>); {"agents": {"research": {"model": "provider/model", "thoughtLevel": "low", "prompt": "short role description"}}}`,
+        `[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), and INCLUDE a proposed short stable `pool` namespace for sub-pool files so ids survive directory renames. File edits, creations, and deletions apply at the next config hook — no host restart; only the anchor set itself is fixed at host start (re-initializations add pools, never remove)."
+        "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)."
       ];
       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 NO host anchor covers it (${anchorNote}). A host initialization in that workspace adds its pools; or fold the agents into the global layer.`);
+        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}).`);
       }
       throw new Error(lines2.join(`
 `));
@@ -17095,24 +17217,32 @@ var crewBeginTool = tool({
       const localOnly = Object.keys(sessionLoaded?.agents ?? {});
       if (localOnly.length > 0) {
         disclosure = `
-[forge:crew] NOTE: this session's workspace has its own forge.json (${sessionProject}) defining ${localOnly.map((id) => `forge-<ns>-${id} (namespaced by its pool)`).join(", ")} — NOT dispatchable on this host (no anchor covers it; anchors: ${hostAnchors.join(", ") || "none"}). A host initialization in that workspace adds its pools, or fold the agents into the global layer.`;
+[forge:crew] NOTE: this session's workspace has its own forge.json (${sessionProject}) defining ${localOnly.map((id) => `forge-<ns>-${id} (namespaced by its pool)`).join(", ")} — NOT dispatchable from this session (this host has not materialized that file). Re-initialize the host in that workspace, or move the agents into the global layer (${globalPoolPath}).`;
       }
     }
-    const familyLines = [];
     const families = resolution?.families ?? [];
+    const familyLines = [];
+    if (sessionFamily) {
+      familyLines.push(`   - DISPATCHABLE from this session — ${sessionPool ? "workspace pool" : "global fallback"}: ${sessionFamily.file} — ${sessionFamily.materializedIds.map((id) => `forge-${id}`).join(", ") || "no agents"}`);
+    }
     for (const f of families.slice(0, 8)) {
-      const label = f.primary ? "root pool (PRIMARY, plain ids)" : `pool ${f.ns} (forge-${f.ns}-*)`;
-      familyLines.push(`   - ${label}: ${f.file} — ${f.materializedIds.map((id) => `forge-${id}`).join(", ") || "no agents"}`);
+      if (f === sessionFamily)
+        continue;
+      const label = f.primary ? "primary pool (plain forge-<id> ids)" : `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)
       familyLines.push(`   - …and ${families.length - 8} more pools`);
     const lines = [
       ...recordNote ? [recordNote] : [],
-      ...lineage ? [`Lineage: ${lineage}`] : [],
+      ...lineage ? [
+        `Lineage: ${lineage}`,
+        `RELAY RULE: this crew descends from ${lineage} — every dispatch prompt must explicitly carry the artifact path (or its exact slice), and every close-report evidence statement must name the contract it worked against.`
+      ] : [],
       governed ? `[forge:crew] Crew registered UNDER THE GOVERNING GOAL — born armed, never pends. Objective: ${objectiveText}` : `[forge:crew] Crew registered PENDING for this session (execution has NOT started). Objective: ${objectiveText}`,
       `Declared plan (${subtasks.length}):`,
       ...subtasks.map((s, i) => `  ${i + 1}. ${s.title}${s.agent ? ` → ${s.agent}` : ""}`),
-      `Dispatchable roster origin — ${families.length} pool${families.length === 1 ? "" : "s"} across the host anchor set${hostAnchors.length > 0 ? ` (anchors: ${hostAnchors.join(", ")})` : ""}:`,
+      `Session roster origins — sole ownership (dispatch gated to this session's workspace pool / the global fallback); ${families.length} pool${families.length === 1 ? "" : "s"} materialized on this host:`,
       ...familyLines,
       ...disclosure ? [disclosure] : []
     ];
@@ -17602,7 +17732,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 — only meaningful for sub-pool files)", agents: { research: { model: "provider/model", thoughtLevel: "low", 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: "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(`
 `).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";
@@ -17632,14 +17762,35 @@ var server = async (input, options) => {
         }
       }
       if (input2.tool === "task") {
+        const a = output?.args ?? {};
+        const target = typeof a.subagent_type === "string" ? a.subagent_type : typeof a.agent === "string" ? a.agent : undefined;
         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 (target && target.toLowerCase().startsWith("forge-") && input2.sessionID) {
+          const resolution = resolvePools();
+          const agentId = target.slice("forge-".length);
+          const entry = resolution?.agents[agentId];
+          if (resolution && entry) {
+            const bound = sessions.get(input2.sessionID);
+            const anchor = bound?.worktree ?? "";
+            if (!anchor) {
+              if (!poolGateUnknownNotes.has(input2.sessionID)) {
+                poolGateUnknownNotes.add(input2.sessionID);
+                console.warn(`[forge:pool] session ${input2.sessionID}: task dispatch to ${target} passed an UNGATED pool check — the session's workspace could not be established (fail-open belt posture; pool ownership unscoped).`);
+              }
+            } else {
+              const sessionPool = sessionPoolFileOf(anchor);
+              const allowed = sessionPool ?? globalPoolPathOf();
+              if (allowed === null || foldPath(entry.file) !== foldPath(allowed)) {
+                throw new Error(`[forge:pool] Dispatch refused: "${target}" belongs to the pool ${entry.file} — not dispatchable from this session. ` + `This session's dispatchable roster is ${sessionPool ? `its workspace pool (${sessionPool})` : `the global fallback (${globalPoolPathOf()})`}. ` + `Exits: open a session in that pool's workspace, or configure the role into this workspace's pool (its .opencode/forge.json), or into the global layer (${globalPoolPathOf()}).`);
+              }
+            }
+          }
+        }
         const pendingCrew = input2.sessionID ? crews.get(input2.sessionID) : undefined;
         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.`);
@@ -17678,13 +17829,42 @@ var server = async (input, options) => {
                     roster.push(`forge-${id}`);
               }
               roster.sort();
-              throw new Error(`[forge] A plan is in draft; dispatch is denied for this target. ` + (roster.length > 0 ? `Readonly recon scouts ARE dispatchable during draft: ${roster.join(", ")}. ` : `No readonly worker is configured — define one in forge.json (shape defaults to readonly) to enable draft-phase reconnaissance. `) + `Write-shaped workers and native agents wait for approval (plan_approve); /plan discard to abandon the plan.`);
+              throw new Error(`[forge] A plan is in draft; dispatch is denied for this target. ` + (roster.length > 0 ? `Readonly recon scouts ARE dispatchable during draft: ${roster.join(", ")}. ` : `No readonly worker is configured — define one in forge.json with an explicit "shape": "readonly" to enable draft-phase reconnaissance. `) + `Write-shaped workers and native agents wait for approval (plan_approve); /plan discard to abandon the plan.`);
             }
           } else {
             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.tool === "forge_shell" && input2.sessionID) {
+        const a = output?.args ?? {};
+        const cmd = typeof a.command === "string" ? a.command : undefined;
+        if (cmd) {
+          const speaker = sessionAgents.get(input2.sessionID);
+          const workerId = speaker !== undefined && isForgeFamilyAgent(speaker) && speaker.toLowerCase() !== FORGE_AGENT ? speaker.slice("forge-".length) : undefined;
+          if (workerId !== undefined) {
+            const def = resolvePools()?.agents[workerId]?.def;
+            if (def !== undefined && effectiveReadonlyShape(def)) {
+              const verdict = classifyExecCommand(cmd);
+              if (verdict.klass === WRITE_CLASS) {
+                const seen = sealFindings.get(input2.sessionID) ?? new Set;
+                if (!seen.has(verdict.indicator)) {
+                  seen.add(verdict.indicator);
+                  sealFindings.set(input2.sessionID, seen);
+                  console.warn(`[forge:seal] session ${input2.sessionID} (readonly worker "${speaker}"): write-class forge_shell command denied — indicator "${verdict.indicator}" (${verdict.detail ?? cmd.slice(0, 60)}). Remedy: "shape": "write" on the agent when its job legitimately mutates.`);
+                }
+                throw new Error(`[forge:seal] Exec refused: this session runs the readonly worker "${speaker}" (explicit "shape": "readonly") and the command was classified WRITE-CLASS — indicator "${verdict.indicator}"${verdict.detail ? ` (${verdict.detail})` : ""}. READ-CLASS commands (inspection, search, read-only evals) flow normally. If this worker's job legitimately mutates, set "shape": "write" on its forge.json entry. Report this refusal VERBATIM — do not work around it.`);
+              }
+            }
+          } else if (speaker === undefined) {
+            const verdict = classifyExecCommand(cmd);
+            if (verdict.klass === WRITE_CLASS && !sealUnknownNotes.has(input2.sessionID)) {
+              sealUnknownNotes.add(input2.sessionID);
+              console.warn(`[forge:seal] session ${input2.sessionID}: a WRITE-CLASS forge_shell command (${verdict.indicator}) flowed UNSEALED — the session's agent is unknown (fail-open; the exec seal binds explicit-readonly forge-* workers only).`);
+            }
+          }
+        }
+      }
       if (input2.sessionID && typeof input2.tool === "string") {
         const speaker = sessionAgents.get(input2.sessionID);
         if (speaker !== undefined) {
@@ -17762,6 +17942,7 @@ var server = async (input, options) => {
     },
     __forgeSubagentsTest: {
       crews: () => crews,
+      sealFindings: (sessionID) => [...sealFindings.get(sessionID) ?? []],
       depthState: (sessionID) => sessionDepths.get(sessionID)?.translation ?? null,
       depthFinding: (agentId) => depthFindingNotes.get(agentId) ?? null,
       catalog: () => modelsDevCatalog,
@@ -17776,7 +17957,8 @@ var server = async (input, options) => {
         poolResolution = null;
       },
       anchors: () => [...hostAnchors],
-      resolveNow: () => resolvePools()
+      resolveNow: () => resolvePools(),
+      workspacePoolOf: (anchor) => sessionPoolFileOf(anchor)
     },
     "permission.ask": async (input2, output) => {
       const meta = input2.metadata ?? {};
@@ -17824,6 +18006,9 @@ var server = async (input, options) => {
           jobManager.onSessionEnd(info.id);
           sessionDepths.delete(info.id);
           sessionAgents.delete(info.id);
+          sealFindings.delete(info.id);
+          sealUnknownNotes.delete(info.id);
+          poolGateUnknownNotes.delete(info.id);
         }
       }
     },

package/package.json

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