@sorenllm/opencode-forge 0.9.1 → 0.11.0

package/README.md

@@ -171,7 +171,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 |
-| `<project>/.opencode/forge.json`, `~/.config/opencode/forge.json` | your static subagent definitions (JSONC). **User data — the plugin only reads it, never writes or migrates it** | yours — version the project one, keep the global one out of sync tools if it holds machine-specific models |
+| the nearest `.opencode/forge.json` on the workspace's ancestor chain, `~/.config/opencode/forge.json` | your static subagent definitions (JSONC), two MERGED layers (project overrides global per agent id). **User data — the plugin only reads it, never writes or migrates it** | yours — version the project one, 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 |
 
@@ -275,6 +275,23 @@ Every result form carries `cwd:` — the absolute directory the command
 actually ran in. When the agent's narrative about the working directory
 disagrees with that line, the line wins.
 
+**Interpreter selection.** Commands run under the host-aligned shell —
+the same interpreter the host's builtin shell tool uses — never under
+Node's `shell: true` default (cmd.exe / plain sh). On Windows the chain
+is `pwsh → powershell → git-bash → %COMSPEC%` (cmd.exe only as a
+machine-level capability fallback); on POSIX the login shell with bash
+preferred and `/bin/sh` as the fallback. PowerShell-family shells are
+invoked directly (`<shell> -NoProfile -Command <command>` plus an
+exit-code guard, so a native command's exit status propagates as the
+job's exit status) — which means you write PowerShell syntax in
+`forge_shell` on Windows: `echo $env:USERNAME` expands, quoted-exe
+invocations use the call operator (`& "C:\path with spaces\tool.exe" args`).
+The tool description states the interpreter family, and there is no
+configuration knob: the interpreter follows the host, by design.
+Goal-harness verification checks run through the same resolver, so a
+check drafted under the model's shell expectations behaves identically
+at the completion gate.
+
 **`forge_jobs`** manages the registry: `list` / `poll {jobId, waitMs≤30s}`
 (bounded wait for new output or exit, drains it) / `log {jobId, offset?,
 limit?}` (line paging over the on-disk log) / `kill` (whole process tree) /
@@ -388,11 +405,28 @@ subagent behavior is untouched. Onboarding is this README, for you the human.
 
 ### forge.json — the configuration
 
-A dedicated `forge.json` (JSONC — comments allowed), resolved by a two-level
-cascade with a single winning source (never merged):
-
-1. `<project>/.opencode/forge.json` — project-level, versionable, team-shared
-2. `~/.config/opencode/forge.json` — global
+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 (error finding with the
+parse location); the other layer still applies. Both layers hot-apply —
+edits, and files appearing or disappearing on the ancestor chain, take
+effect without a host restart (new agents still need the restart to enter
+the task vocabulary; see the apply-timing table below).
+
+One host instance materializes one pool (from its launch anchor) — a
+workspace-local file that the host was not launched on is NOT silently
+ignored: `/crew` names it and tells you to relaunch there (or fold the
+agents into the global layer).
 
 ```jsonc
 {
@@ -605,6 +639,32 @@ supervisor chapter above). The hide is unconditional: it covers a
 `jobs.keepBuiltinShell: true` (builtin shell back on the forge family) and
 `jobs.mode: "native"` (supervisor retired entirely).
 
+### The exec channel is final for this plugin-API generation (2026-09-28)
+
+The four layers — tools-map hide, prompt mandate, belt refusal, `forge_shell`
+itself — are the ceiling of what the current opencode plugin API can express,
+and the design is closed deliberately:
+
+- **Not expressible**: `tool.execute.before` can only mutate `args` or throw.
+  There is no tool-name rewrite, no executor replacement, no result injection —
+  "transparently reroute a builtin bash call through the job runner" cannot be
+  written. Registering a plugin tool named `bash` collides globally: tool
+  registration is not per-agent, and the per-agent mechanism is exactly the
+  tools map some hosts ignore.
+- **Prior art ships a subset**: OMO (oh-my-opencode-slim / oh-my-openagent,
+  the largest opencode plugin ecosystem) pairs a permission-deny boundary with
+  a prompt channel mandate and does not hide the builtin shell at plugin level
+  either — their models also see bash and pay one denial round.
+- **The residual is bounded and accepted**: on hosts where the hide does not
+  hold, a first bash attempt costs one round-trip per session — the belt
+  refuses pre-execution (~2 ms, the command never runs), the message names
+  `forge_shell`, and models re-issue once and stay on-channel. Field data
+  (2026-09-28): zero duplicate executions attributable to the belt.
+- **Reopen on upstream movement**: hosts honoring injected tools maps (the
+  belt becomes pure insurance), a tool-execute replacement hook (transparent
+  rerouting becomes expressible), or exit-based builtin-shell completion (the
+  watchdog retirement path above applies).
+
 A process restart forgets the session binding: the write-ban soft-disables
 (safety over strictness) and the next session's system notice + `/plan
 resume` re-bind from the plan file on disk, which is the source of truth.

package/dist/index.js

@@ -12335,8 +12335,8 @@ 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 readdirSync4, readFileSync as readFileSync8, statSync as statSync4, writeFileSync as writeFileSync5 } from "node:fs";
-import { isAbsolute, join as join5, relative } from "node:path";
+import { appendFileSync, existsSync as existsSync3, mkdirSync as mkdirSync5, readdirSync as readdirSync4, readFileSync as readFileSync8, 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";
 
 // src/plan-file.ts
@@ -13118,13 +13118,97 @@ function completeCheckFailures(doc2, attestations) {
 // src/run-check.ts
 import { spawn as spawn2 } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { join, resolve, sep } from "node:path";
+import { join as join2, resolve, sep } from "node:path";
+
+// src/proc.ts
+import { spawn, spawnSync as spawnSync2 } from "node:child_process";
+
+// src/shell-select.ts
+import { spawnSync } from "node:child_process";
+import { statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+var hostConfiguredShell;
+var memo;
+function setHostShell(shell) {
+  hostConfiguredShell = shell && shell.trim() ? shell.trim() : undefined;
+  memo = undefined;
+}
+var DENY = new Set(["fish", "nu"]);
+function shellName(bin) {
+  return basename(bin).replace(/\.exe$/i, "").toLowerCase();
+}
+function classify(bin) {
+  const name = shellName(bin);
+  if (name === "pwsh" || name === "powershell")
+    return { bin, family: "ps", login: false };
+  if (name === "cmd")
+    return { bin, family: "cmd", login: false };
+  return { bin, family: "posix", login: name === "bash" || name === "zsh" };
+}
+function defaultWhich(platform, env) {
+  return (bin) => {
+    try {
+      const r = spawnSync(platform === "win32" ? "where" : "which", [bin], {
+        env,
+        windowsHide: true,
+        timeout: 5000
+      });
+      if (r.status !== 0 || !r.stdout)
+        return;
+      const first = r.stdout.toString().split(/\r?\n/).find((l) => l.trim());
+      return first?.trim() || undefined;
+    } catch {
+      return;
+    }
+  };
+}
+function defaultStat(file2) {
+  return statSync(file2, { throwIfNoEntry: false }) ?? undefined;
+}
+function gitBash(which, stat) {
+  const git = which("git");
+  if (!git)
+    return;
+  const candidate = join(dirname(dirname(git)), "bin", "bash.exe");
+  return stat(candidate)?.isFile() ? candidate : undefined;
+}
+function resolveShell(deps = {}) {
+  const hasDeps = Object.keys(deps).length > 0;
+  if (!hasDeps && memo)
+    return memo;
+  const platform = deps.platform ?? process.platform;
+  const env = deps.env ?? process.env;
+  const which = deps.which ?? defaultWhich(platform, env);
+  const stat = deps.stat ?? defaultStat;
+  const pick2 = (candidate) => {
+    if (!candidate)
+      return;
+    if (DENY.has(shellName(candidate)))
+      return;
+    const resolved = /^[a-z]:[\\/]/i.test(candidate) || candidate.includes("/") || candidate.includes("\\") ? stat(candidate)?.isFile() ? candidate : which(candidate) : which(candidate);
+    return resolved ? classify(resolved) : undefined;
+  };
+  let result = pick2(hostConfiguredShell);
+  if (!result && platform === "win32") {
+    result = pick2("pwsh") ?? pick2("powershell") ?? pick2(gitBash(which, stat)) ?? pick2(env.COMSPEC || "cmd.exe");
+  }
+  if (!result && platform !== "win32") {
+    result = pick2(env.SHELL) ?? pick2("bash") ?? pick2("/bin/sh");
+  }
+  if (!result) {
+    result = platform === "win32" ? { bin: env.COMSPEC || "cmd.exe", family: "cmd", login: false } : { bin: "/bin/sh", family: "posix", login: false };
+  }
+  if (!hasDeps)
+    memo = result;
+  return result;
+}
 
 // src/proc.ts
-import { spawn, spawnSync } from "node:child_process";
 function shellSpawn(spawnFn, cmd, opts = {}) {
-  return spawnFn(cmd, {
-    shell: true,
+  const shell = opts.shell ?? resolveShell();
+  const argv = shell.family === "ps" ? ["-NoProfile", "-Command", `${cmd}
+exit $LASTEXITCODE`] : shell.family === "cmd" ? ["/c", cmd] : shell.login ? ["-l", "-c", cmd] : ["-c", cmd];
+  return spawnFn(shell.bin, argv, {
     ...opts.cwd !== undefined ? { cwd: opts.cwd } : {},
     env: opts.env ? { ...process.env, ...opts.env } : process.env,
     windowsHide: opts.windowsHide ?? true,
@@ -13171,7 +13255,7 @@ function pidAlive(pid) {
 function terminateTreeSync(pid, opts = {}) {
   const graceMs = Math.max(0, opts.graceMs ?? 0);
   const platform = opts.platform ?? process.platform;
-  const sync = opts.spawnSyncFn ?? spawnSync;
+  const sync = opts.spawnSyncFn ?? spawnSync2;
   const wait = opts.wait ?? true;
   const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
   const run = (force) => {
@@ -13207,12 +13291,7 @@ var OUTPUT_LIMIT = 2048;
 var defaultShellRunner = (cmd, opts) => new Promise((resolveRun) => {
   let child;
   try {
-    child = spawn2(cmd, {
-      shell: true,
-      cwd: opts.cwd,
-      windowsHide: true,
-      ...process.platform !== "win32" ? { detached: true } : {}
-    });
+    child = shellSpawn(spawn2, cmd, { cwd: opts.cwd });
   } catch (err) {
     resolveRun({ code: null, output: "", timedOut: false, spawnError: String(err) });
     return;
@@ -13281,7 +13360,7 @@ function runContainsItem(item, index, worktree) {
   if (!insideWorktree(worktree, item.file)) {
     return { index, kind: "contains", label, ok: false, detail: "path escapes the workspace boundary", durationMs: Date.now() - started };
   }
-  const abs = join(worktree, item.file);
+  const abs = join2(worktree, item.file);
   let content;
   try {
     content = readFileSync(abs, "utf8");
@@ -13570,8 +13649,8 @@ function newJobId(now = Date.now) {
 
 // src/job-runner.ts
 import { spawn as spawn3 } from "node:child_process";
-import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readSync, readFileSync as readFileSync2, statSync, unlinkSync } from "node:fs";
-import { join as join2 } from "node:path";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readSync, readFileSync as readFileSync2, statSync as statSync2, unlinkSync } from "node:fs";
+import { join as join3 } from "node:path";
 import { tmpdir } from "node:os";
 var DEFAULT_IDLE_MS = 60000;
 var DEFAULT_MAX_WAIT_MS = 120000;
@@ -13582,17 +13661,17 @@ var JOB_ENV_MARKER = "FORGE_JOB_ID";
 var TAIL_POLL_MS = 200;
 var ADOPT_LIVENESS_MS = 1000;
 function jobsLogDir(base) {
-  return join2(base ?? join2(tmpdir(), "opencode-forge"), "jobs");
+  return join3(base ?? join3(tmpdir(), "opencode-forge"), "jobs");
 }
 var TAIL_CHUNK_BYTES = 4 * 1024 * 1024;
 function createFileTail(logPath, onText, pollMs = TAIL_POLL_MS) {
-  let pos = existsSync(logPath) ? statSync(logPath).size : 0;
+  let pos = existsSync(logPath) ? statSync2(logPath).size : 0;
   let stopped = false;
   const flush = () => {
     if (stopped)
       return;
     try {
-      let size = existsSync(logPath) ? statSync(logPath).size : 0;
+      let size = existsSync(logPath) ? statSync2(logPath).size : 0;
       if (size < pos)
         pos = size;
       const fd = openSync(logPath, "r");
@@ -13611,7 +13690,7 @@ function createFileTail(logPath, onText, pollMs = TAIL_POLL_MS) {
             break;
           pos += read;
           onText(buf.toString("utf8", 0, read));
-          size = existsSync(logPath) ? statSync(logPath).size : size;
+          size = existsSync(logPath) ? statSync2(logPath).size : size;
           if (stopped)
             break;
         }
@@ -13639,7 +13718,7 @@ function startJob(manager, opts) {
   const maxWaitMs = Math.min(Math.max(0, opts.maxWaitMs ?? DEFAULT_MAX_WAIT_MS), HARD_MAX_WAIT_MS);
   mkdirSync(opts.logDir, { recursive: true });
   const id = newJobId();
-  const logPath = join2(opts.logDir, `${id}.log`);
+  const logPath = join3(opts.logDir, `${id}.log`);
   let child;
   let settled = false;
   let exiting = false;
@@ -13695,6 +13774,7 @@ function startJob(manager, opts) {
   try {
     wfd = openSync(logPath, "a");
     child = shellSpawn(opts.spawnFn ?? spawn3, opts.cmd, {
+      shell: opts.shell,
       cwd: opts.cwd,
       env: { ...opts.env ?? {}, [JOB_ENV_MARKER]: id },
       stdio: ["ignore", wfd, wfd]
@@ -13872,7 +13952,7 @@ function readJobLog(logPath, opts = {}) {
   let windowed = false;
   try {
     if (existsSync(logPath)) {
-      const size = statSync(logPath).size;
+      const size = statSync2(logPath).size;
       if (size > LOG_READ_MAX_BYTES) {
         const fd = openSync(logPath, "r");
         try {
@@ -13910,7 +13990,7 @@ function rotateLogs(logDir, keep = DEFAULT_LOG_KEEP) {
   try {
     entries = readdirSync(logDir).filter((f) => f.endsWith(".log")).map((name) => {
       try {
-        return { name, mtime: statSync(join2(logDir, name)).mtimeMs };
+        return { name, mtime: statSync2(join3(logDir, name)).mtimeMs };
       } catch {
         return { name, mtime: 0 };
       }
@@ -13924,7 +14004,7 @@ function rotateLogs(logDir, keep = DEFAULT_LOG_KEEP) {
   entries.sort((a, b) => a.mtime - b.mtime);
   for (const e of entries.slice(0, excess)) {
     try {
-      unlinkSync(join2(logDir, e.name));
+      unlinkSync(join3(logDir, e.name));
     } catch {}
   }
 }
@@ -14144,9 +14224,9 @@ function createJobFence(opts = {}) {
 }
 
 // src/job-registry.ts
-import { closeSync as closeSync2, existsSync as existsSync2, mkdirSync as mkdirSync2, openSync as openSync2, readFileSync as readFileSync3, readdirSync as readdirSync2, statSync as statSync2, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { closeSync as closeSync2, existsSync as existsSync2, mkdirSync as mkdirSync2, openSync as openSync2, readFileSync as readFileSync3, readdirSync as readdirSync2, statSync as statSync3, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { execFileSync, spawn as spawn5 } from "node:child_process";
-import { dirname, join as join3 } from "node:path";
+import { dirname as dirname2, join as join4 } from "node:path";
 var REGISTRY_KEEP = 100;
 function structuralRelocate(deadPid, platform = process.platform) {
   if (deadPid <= 0)
@@ -14226,7 +14306,7 @@ function acquireLock(lockPath, timeoutMs = 2000) {
       if (err.code !== "EEXIST")
         throw err;
       try {
-        if (Date.now() - statSync2(lockPath).mtimeMs > 5000) {
+        if (Date.now() - statSync3(lockPath).mtimeMs > 5000) {
           unlinkSync2(lockPath);
           continue;
         }
@@ -14251,7 +14331,7 @@ function readRaw(path) {
   }
 }
 function writeRaw(path, entries) {
-  mkdirSync2(dirname(path), { recursive: true });
+  mkdirSync2(dirname2(path), { recursive: true });
   writeFileSync2(path, `${JSON.stringify({ version: 1, entries: entries.slice(0, REGISTRY_KEEP) }, null, 2)}
 `);
 }
@@ -14307,7 +14387,7 @@ function createJobRegistry(registryPath) {
   };
 }
 function registryPathFor(jobsDir) {
-  return join3(jobsDir, "registry.json");
+  return join4(jobsDir, "registry.json");
 }
 
 // src/host-exit.ts
@@ -14389,7 +14469,7 @@ function createExitCleanup(manager, opts = {}) {
 
 // src/watchdog.ts
 import { mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "node:fs";
-import { dirname as dirname2 } from "node:path";
+import { dirname as dirname3 } from "node:path";
 var WATCHDOG_ENV_MARK = "FORGE_WATCHDOG_MARK";
 var DEFAULT_STALL_MS = 600000;
 var MIN_STALL_MS = 60000;
@@ -14607,7 +14687,7 @@ function watchdogLogDir(base) {
 function createFileLedger(logPath, maxEntries = 200, maxBytes = 1e6) {
   const append = (entry) => {
     try {
-      mkdirSync3(dirname2(logPath), { recursive: true });
+      mkdirSync3(dirname3(logPath), { recursive: true });
       let lines = [];
       try {
         lines = readFileSync4(logPath, "utf8").split(`
@@ -14760,7 +14840,7 @@ function createLocator(platform = process.platform, posix = {}, win = {}) {
 
 // src/models-dev.ts
 import { mkdirSync as mkdirSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "node:fs";
-import { join as join4 } from "node:path";
+import { join as join5 } from "node:path";
 import { tmpdir as tmpdir2 } from "node:os";
 var DEFAULT_MODELS_DEV_URL = "https://models.dev/api.json";
 function parseIdentity(identity) {
@@ -14782,7 +14862,7 @@ function nativeLadder(catalog, identity) {
   return Array.isArray(options) ? [...options] : null;
 }
 function modelsDevCacheDir(base) {
-  return join4(base ?? join4(tmpdir2(), "opencode-forge"), "models-dev");
+  return join5(base ?? join5(tmpdir2(), "opencode-forge"), "models-dev");
 }
 function namedLevels(rows) {
   const out = [];
@@ -14824,7 +14904,7 @@ function reduceModelsDev(raw) {
 async function loadModelsDevSnapshot(opts = {}) {
   const url2 = opts.url ?? process.env.OPENCODE_MODELS_URL ?? DEFAULT_MODELS_DEV_URL;
   const cacheDir = modelsDevCacheDir(opts.cacheDir);
-  const cacheFile = join4(cacheDir, "snapshot.json");
+  const cacheFile = join5(cacheDir, "snapshot.json");
   const fetcher = opts.fetcher;
   if (fetcher) {
     try {
@@ -15024,7 +15104,7 @@ function resolvePinnedDepth(thoughtLevel, family, ladder) {
 }
 
 // src/forge-config.ts
-import { readFileSync as readFileSync7, statSync as statSync3 } from "node:fs";
+import { readFileSync as readFileSync7, statSync as statSync4 } from "node:fs";
 function sanitizeJsonc(text) {
   const out = [];
   let i = 0;
@@ -15349,17 +15429,35 @@ function forgeConfigPaths(opts) {
   const global = opts.homeDir ? `${opts.homeDir}${sep2}.config${sep2}opencode${sep2}forge.json` : "";
   return { project, global };
 }
+function isFsRoot(p) {
+  return p === "" || p === "/" || p === "\\" || /^[A-Za-z]:[\\/]?$/.test(p);
+}
+function parentDirOf(p) {
+  let s = p;
+  while (s.endsWith("/") || s.endsWith("\\")) {
+    if (isFsRoot(s))
+      return null;
+    s = s.slice(0, -1);
+    if (isFsRoot(s))
+      return null;
+  }
+  const i = Math.max(s.lastIndexOf("/"), s.lastIndexOf("\\"));
+  if (i < 0)
+    return null;
+  const parent = s.slice(0, i + 1);
+  return parent === "" ? null : parent;
+}
 function createForgeConfigLoader(deps) {
   const stat = deps.stat ?? ((path) => {
     try {
-      const s = statSync3(path);
+      const s = statSync4(path);
       return { mtimeMs: s.mtimeMs, size: s.size };
     } catch {
       return null;
     }
   });
   const readFile = deps.readFile ?? ((path) => readFileSync7(path, "utf8"));
-  const paths = forgeConfigPaths({ projectDir: deps.projectDir, homeDir: deps.homeDir });
+  const globalPath = forgeConfigPaths({ homeDir: deps.homeDir }).global;
   const cache = new Map;
   const readCandidate = (path, source) => {
     const st = stat(path);
@@ -15378,11 +15476,12 @@ function createForgeConfigLoader(deps) {
         agents: {},
         source,
         path,
+        projectPath: source === "project" ? path : null,
         findings: [
           {
             level: "error",
             code: "config-parse-error",
-            message: `${path}: ${parsed.error.message}${parsed.error.line !== undefined ? ` (line ${parsed.error.line}, column ${parsed.error.column})` : ""} — the agent set is empty until the file parses`
+            message: `${path}: ${parsed.error.message}${parsed.error.line !== undefined ? ` (line ${parsed.error.line}, column ${parsed.error.column})` : ""} — this layer contributes no agents until the file parses`
           }
         ]
       };
@@ -15393,25 +15492,55 @@ function createForgeConfigLoader(deps) {
           agents: {},
           source,
           path,
-          findings: [{ level: "error", code: "config-not-object", message: `${path}: top level must be an object — the agent set is empty` }]
+          projectPath: source === "project" ? path : null,
+          findings: [{ level: "error", code: "config-not-object", message: `${path}: top level must be an object — this layer contributes no agents` }]
         };
       } else {
         const validated = validateAgentSet(top === undefined ? undefined : top.agents);
-        result = { agents: validated.agents, source, path, findings: validated.findings };
+        result = { agents: validated.agents, source, path, projectPath: source === "project" ? path : null, findings: validated.findings };
       }
     }
     cache.set(path, { mtimeMs: st.mtimeMs, size: st.size, result });
     return result;
   };
+  const candidateAt = (dir) => {
+    const sep2 = dir.includes("\\") && !dir.includes("/") ? "\\" : "/";
+    const base = dir.endsWith("/") || dir.endsWith("\\") ? dir : `${dir}${sep2}`;
+    return `${base}.opencode${sep2}forge.json`;
+  };
+  const discoverProjectFile = (anchor) => {
+    let dir = (anchor ?? "").trim();
+    if (!dir)
+      return null;
+    for (;; ) {
+      const candidate = candidateAt(dir);
+      if (stat(candidate) !== null)
+        return candidate;
+      const parent = parentDirOf(dir);
+      if (parent === null || parent === dir)
+        return null;
+      dir = parent;
+    }
+  };
   return {
     load() {
-      const project = paths.project ? readCandidate(paths.project, "project") : null;
+      const projectPath = discoverProjectFile(deps.projectDir ?? "");
+      const project = projectPath ? readCandidate(projectPath, "project") : null;
+      const global = globalPath ? readCandidate(globalPath, "global") : null;
+      if (project && global) {
+        return {
+          agents: { ...global.agents, ...project.agents },
+          source: "project+global",
+          path: project.path,
+          projectPath: project.path,
+          findings: [...global.findings, ...project.findings]
+        };
+      }
       if (project)
-        return project;
-      const global = paths.global ? readCandidate(paths.global, "global") : null;
+        return { agents: project.agents, source: "project", path: project.path, projectPath: project.path, findings: project.findings };
       if (global)
-        return global;
-      return { agents: {}, source: "none", path: null, findings: [] };
+        return { agents: global.agents, source: "global", path: global.path, projectPath: null, findings: global.findings };
+      return { agents: {}, source: "none", path: null, projectPath: null, findings: [] };
     }
   };
 }
@@ -15529,6 +15658,22 @@ function noteToolAgent(context) {
 var forgeDisabled = false;
 var forgeLoader = null;
 var forgeLoaderDir = null;
+var sessionAnchorLoaders = new Map;
+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() });
+    sessionAnchorLoaders.set(key, l);
+    while (sessionAnchorLoaders.size > 8) {
+      const oldest = sessionAnchorLoaders.keys().next().value;
+      if (oldest === undefined)
+        break;
+      sessionAnchorLoaders.delete(oldest);
+    }
+  }
+  return l;
+}
 var crews = new Map;
 var modelsDevCatalog = null;
 var depthFindingNotes = new Map;
@@ -15596,11 +15741,11 @@ function jobStage() {
   return 0;
 }
 var jobLogDir = jobsLogDir();
-var jobLedgerPath = join5(jobLogDir, "ledger.jsonl");
+var jobLedgerPath = join6(jobLogDir, "ledger.jsonl");
 function jobLedgerSink(entry) {
   try {
     mkdirSync5(jobLogDir, { recursive: true });
-    if (existsSync3(jobLedgerPath) && statSync4(jobLedgerPath).size > 1e6)
+    if (existsSync3(jobLedgerPath) && statSync5(jobLedgerPath).size > 1e6)
       writeFileSync5(jobLedgerPath, "");
     appendFileSync(jobLedgerPath, `${JSON.stringify(entry)}
 `);
@@ -15663,13 +15808,13 @@ function nowIso() {
   return new Date().toISOString();
 }
 function planDirOf(worktree) {
-  return join5(worktree, ".opencode", "plan");
+  return join6(worktree, ".opencode", "plan");
 }
 function readPlanDir(worktree) {
   const dir = planDirOf(worktree);
   if (!existsSync3(dir))
     return [];
-  return readdirSync4(dir).filter((f) => f.endsWith(".md")).map((name) => ({ name, text: readFileSync8(join5(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);
@@ -15681,9 +15826,15 @@ function ensureSession(sessionID, worktree) {
   sessions.set(sessionID, state);
   return state;
 }
+function sessionAnchor(context) {
+  const viaDir = effectiveWorktree(context.worktree, context.directory);
+  if (viaDir && !isRootish(viaDir))
+    return viaDir;
+  return hostWorktree || (context.worktree ?? "").trim() || (context.directory ?? "").trim();
+}
 function worktreeFor(context) {
   noteToolAgent(context);
-  return effectiveWorktree(context.worktree, hostWorktree) || context.worktree;
+  return sessionAnchor(context) || context.worktree;
 }
 function resolveActivePlan(state) {
   if (state.planPath && existsSync3(state.planPath)) {
@@ -15695,7 +15846,7 @@ function resolveActivePlan(state) {
   const ranked = rankActivePlans(readPlanDir(state.worktree));
   if (ranked.length === 0)
     return null;
-  const path = join5(planDirOf(state.worktree), ranked[0].name);
+  const path = join6(planDirOf(state.worktree), ranked[0].name);
   state.planPath = path;
   return { path, doc: ranked[0].doc };
 }
@@ -15730,7 +15881,7 @@ var planWriteTool = tool({
     } else {
       const dir = planDirOf(state.worktree);
       mkdirSync5(dir, { recursive: true });
-      path = join5(dir, planFileName(localDate(), slugify(args.goal), readdirSync4(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);
@@ -15848,13 +15999,13 @@ var planDiscardTool = tool({
   }
 });
 function goalDirOf(worktree) {
-  return join5(worktree, ".opencode", "goal");
+  return join6(worktree, ".opencode", "goal");
 }
 function readGoalDir(worktree) {
   const dir = goalDirOf(worktree);
   if (!existsSync3(dir))
     return [];
-  return readdirSync4(dir).filter((f) => f.endsWith(".md")).map((name) => ({ name, text: readFileSync8(join5(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)) {
@@ -15865,7 +16016,7 @@ function resolveSessionGoal(state) {
   }
   const live = rankLiveGoals(readGoalDir(state.worktree))[0];
   if (live) {
-    const path = join5(goalDirOf(state.worktree), live.name);
+    const path = join6(goalDirOf(state.worktree), live.name);
     state.goalPath = path;
     return { path, doc: live.doc };
   }
@@ -15964,7 +16115,7 @@ var goalWriteTool = tool({
     const dir = goalDirOf(state.worktree);
     mkdirSync5(dir, { recursive: true });
     const name = goalFileName(localDateNow(), slugifyGoal(args.goal), readdirSync4(dir).filter((f) => f.endsWith(".md")));
-    const path = join5(dir, name);
+    const path = join6(dir, name);
     const text = renderGoal(input, {
       now,
       status: arm ? "active" : "queued",
@@ -16093,7 +16244,7 @@ var goalResumeTool = tool({
     if (!goal || goal.doc.status === "queued") {
       const oldest = rankQueuedGoals(readGoalDir(state.worktree))[0];
       if (oldest) {
-        const path = join5(goalDirOf(state.worktree), oldest.name);
+        const path = join6(goalDirOf(state.worktree), oldest.name);
         state.goalPath = path;
         goal = { path, doc: oldest.doc };
       }
@@ -16143,7 +16294,8 @@ var FORGE_SHELL_DESCRIPTION = [
   "Run a shell command without ever blocking the session indefinitely. The call completes on the FIRST of: process exit (bound to the exit event — a detached grandchild holding the stdio pipes cannot suspend the call); success_pattern matching new output (opt-in regex); idle_ms with no new output (default 60000); max_wait_ms hard cap (default 120000, max 600000 — returns still-running, never kills).",
   "Idle/max-wait return `still-running` with a jobId — the process stays alive; keep watching with forge_jobs poll / log, stop it with forge_jobs kill. run_in_background returns {jobId, logPath} immediately.",
   "success_pattern semantics: a match completes the call as success; the process is kept alive by default (server semantics — the thing you just verified keeps running); pass keep_alive=false to kill its tree on match. Common patterns: dev servers `listening on|ready in|Local:`, builds `Compiled successfully|Done in`, test suites `passed|all tests`.",
-  "This tool is the forge agent's exec surface for every shell command — quick ones included. Long-running or possibly non-exiting commands (dev servers, watchers, installers, anything spawning detached children) should start with run_in_background and collect results via forge_jobs."
+  "This tool is the forge agent's exec surface for every shell command — quick ones included. Long-running or possibly non-exiting commands (dev servers, watchers, installers, anything spawning detached children) should start with run_in_background and collect results via forge_jobs.",
+  "Interpreter: commands run under the host-preferred shell — the PowerShell family on Windows (git-bash only on machines without PowerShell), the login shell with bash preferred on POSIX — the same interpreter the host's builtin shell tool uses."
 ].join(`
 `);
 var forgeShellTool = tool({
@@ -16175,7 +16327,7 @@ var forgeShellTool = tool({
       }
     }
     const { registry: registry2, fence } = ensureJobLifecycle();
-    const cwd = args.workdir ? isAbsolute(args.workdir) ? args.workdir : join5(state.worktree, args.workdir) : state.worktree;
+    const cwd = args.workdir ? isAbsolute(args.workdir) ? args.workdir : join6(state.worktree, args.workdir) : state.worktree;
     const started = startJob(jobManager, {
       cmd: args.command,
       cwd,
@@ -16336,7 +16488,7 @@ var CREW_INIT_TEMPLATE = [
   "",
   "CREW IS NOT INITIALIZED: no forge subagents are configured (no usable forge.json agents). Refuse to enter orchestration and tell the user this feature needs a one-time setup, offering BOTH options:",
   "",
-  "1. The user configures it themselves: create ONE of these files (project-level wins, never merged):",
+  "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):",
   "{paths}",
   "",
   "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.",
@@ -16382,15 +16534,24 @@ var crewBeginTool = tool({
     if (active && active.doc.status === "draft") {
       throw new Error("[forge:crew] A plan is in draft; crew orchestration is denied during planning. Call plan_approve for user approval, or /plan discard to abandon the plan.");
     }
-    const loaded = forgeLoader?.load();
-    if (!loaded || Object.keys(loaded.agents).length === 0) {
-      const paths = forgeConfigPaths({ projectDir: forgeLoaderDir ?? undefined, homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() });
-      throw new Error([
-        "[forge:crew] CREW IS NOT INITIALIZED: no forge subagents are configured. Crew orchestration is unavailable until the user sets it up.",
-        `Create ONE of these files (project-level wins): ${paths.project} OR ${paths.global}`,
+    const hostLoaded = forgeLoader?.load();
+    const hostIds = hostLoaded ? Object.keys(hostLoaded.agents) : [];
+    const anchor = sessionAnchor(context);
+    const hostAnchorDir = forgeLoaderDir ?? "";
+    const sessionLoaded = anchor && anchor !== hostAnchorDir ? loaderForAnchor(anchor).load() : hostLoaded;
+    const sessionProject = sessionLoaded?.projectPath ?? null;
+    if (hostIds.length === 0) {
+      const paths = forgeConfigPaths({ projectDir: hostAnchorDir || undefined, homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() });
+      const lines = [
+        "[forge:crew] CREW IS NOT INITIALIZED on this host: no forge subagents are materialized. 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}.`,
         'Template (JSONC): {"agents": {"research": {"model": "provider/model", "thoughtLevel": "low"}}}',
         "The user may configure it themselves, or ask you to write the file — only on their explicit go-ahead. Newly added agents need a host restart; thoughtLevel edits apply without one."
-      ].join(`
+      ];
+      if (sessionLoaded && Object.keys(sessionLoaded.agents).length > 0 && sessionProject) {
+        lines.push(`NOTE: this session's workspace DOES have a forge.json (${sessionProject}) with usable agents — but this host instance was launched from ${hostAnchorDir || "a different directory"}, so they are not in the task vocabulary. Relaunch opencode in that workspace, or add the agents to the global layer.`);
+      }
+      throw new Error(lines.join(`
 `));
     }
     if (!args.objective?.trim())
@@ -16416,13 +16577,22 @@ var crewBeginTool = tool({
       throw new Error(`[forge:crew] This session already has an active crew: "${existing.objective}" (started ${existing.startedAt}). Finish and close it with crew_close before starting another.`);
     }
     crews.set(context.sessionID, { objective: args.objective.trim(), startedAt: nowIso(), subtasks });
+    let disclosure = "";
+    if (sessionProject && sessionProject !== (hostLoaded?.projectPath ?? null)) {
+      const localOnly = Object.keys(sessionLoaded?.agents ?? {}).filter((id) => !hostIds.includes(id));
+      if (localOnly.length > 0) {
+        disclosure = `
+[forge:crew] NOTE: this session's workspace has its own forge.json (${sessionProject}) defining ${localOnly.map((id) => `forge-${id}`).join(", ")} — NOT dispatchable on this host (launched from ${hostAnchorDir || "a different directory"}). Relaunch opencode in that workspace to use them, or fold them into the global layer.`;
+      }
+    }
     return {
       title: `crew registered: ${args.objective.trim().slice(0, 60)}`,
       output: [
         `[forge:crew] Crew registered for this session. Objective: ${args.objective.trim()}`,
         `Declared plan (${subtasks.length}):`,
         ...subtasks.map((s, i) => `  ${i + 1}. ${s.title}${s.agent ? ` → ${s.agent}` : ""}`),
-        "Proceed with the discipline: waves of parallel native task calls (next wave after the previous results) → per-subtask evidence verdicts → at most one retry → crew_close with the full report covering every declared subtask."
+        "Proceed with the discipline: waves of parallel native task calls (next wave after the previous results) → per-subtask evidence verdicts → at most one retry → crew_close with the full report covering every declared subtask.",
+        ...disclosure ? [disclosure] : []
       ].join(`
 `)
     };
@@ -16511,7 +16681,7 @@ var pendingContinuationTurn = new Set;
 function goalProbe(line) {
   if (process.env.FORGE_GOAL_PROBE) {
     try {
-      appendFileSync(join5(tmpdir3(), "forge-goal-probe.log"), `${new Date().toISOString()} ${line}
+      appendFileSync(join6(tmpdir3(), "forge-goal-probe.log"), `${new Date().toISOString()} ${line}
 `);
     } catch {}
   }
@@ -16726,14 +16896,14 @@ var server = async (input, options) => {
   if (wdStallRaw !== undefined && wdStallRaw !== wdStall) {
     wdFallbacks.push(`watchdog.stallMs ${JSON.stringify(String(wdStallRaw))} adjusted to ${wdStall} (floor/default applied)`);
   }
-  const watchdogLedger = createFileLedger(join5(watchdogLogDir(), "log.jsonl"));
+  const watchdogLedger = createFileLedger(join6(watchdogLogDir(), "log.jsonl"));
   const rawLocator = createLocator();
   const probing = () => process.env.FORGE_WATCHDOG_PROBE === "1";
   const probeLine = (text) => {
     if (!probing())
       return;
     try {
-      appendFileSync(join5(tmpdir3(), "forge-watchdog-probe.log"), `${new Date().toISOString()} ${text}
+      appendFileSync(join6(tmpdir3(), "forge-watchdog-probe.log"), `${new Date().toISOString()} ${text}
 `);
     } catch {}
   };
@@ -16789,6 +16959,7 @@ var server = async (input, options) => {
       forgeDisabled = forgeUserCfg?.disable === true;
       if (forgeDisabled)
         return;
+      setHostShell(typeof cfg.shell === "string" ? cfg.shell : undefined);
       cfg.default_agent ??= FORGE_AGENT;
       const existing = agentSection[FORGE_AGENT];
       agentSection[FORGE_AGENT] = {
@@ -16893,7 +17064,7 @@ var server = async (input, options) => {
     "tool.execute.before": async (input2, output) => {
       if (process.env.FORGE_PERM_PROBE) {
         try {
-          appendFileSync(join5(tmpdir3(), "forge-perm-probe.log"), `${new Date().toISOString()} before tool=${JSON.stringify(input2.tool)} session=${input2.sessionID}
+          appendFileSync(join6(tmpdir3(), "forge-perm-probe.log"), `${new Date().toISOString()} before tool=${JSON.stringify(input2.tool)} session=${input2.sessionID}
 `);
         } catch {}
       }
@@ -16903,7 +17074,7 @@ var server = async (input, options) => {
         watchdog.track(input2.callID, input2.sessionID, input2.tool, undefined, cmdText !== undefined ? commandNeedle(cmdText) : undefined);
         if (process.env.FORGE_WATCHDOG_PROBE) {
           try {
-            appendFileSync(join5(tmpdir3(), "forge-watchdog-probe.log"), `${new Date().toISOString()} track ${input2.callID} needle=${JSON.stringify(cmdText !== undefined ? commandNeedle(cmdText) : undefined)} rawArgs=${JSON.stringify(output?.args ?? null).slice(0, 200)}
+            appendFileSync(join6(tmpdir3(), "forge-watchdog-probe.log"), `${new Date().toISOString()} track ${input2.callID} needle=${JSON.stringify(cmdText !== undefined ? commandNeedle(cmdText) : undefined)} rawArgs=${JSON.stringify(output?.args ?? null).slice(0, 200)}
 `);
           } catch {}
         }
@@ -16926,7 +17097,7 @@ var server = async (input, options) => {
           if (raw) {
             const state = stateForBan(input2.sessionID);
             const base = state?.worktree ?? hostWorktree ?? "";
-            const abs = (isAbsolute(raw) ? raw : join5(base, raw)).replaceAll("\\", "/").toLowerCase();
+            const abs = (isAbsolute(raw) ? raw : join6(base, raw)).replaceAll("\\", "/").toLowerCase();
             if (abs.includes("/.opencode/plan/") || abs.includes("/.opencode/goal/")) {
               throw new Error(`[forge:partition] Write refused: "${raw}" is inside the forge state directories (.opencode/plan, .opencode/goal), which belong to the forge agent in this workspace.`);
             }
@@ -17017,7 +17188,7 @@ var server = async (input, options) => {
       const name = (typeof meta.tool === "string" ? meta.tool : undefined) ?? (typeof permissionField === "string" ? permissionField : undefined) ?? input2.id ?? input2.type;
       if (process.env.FORGE_PERM_PROBE) {
         try {
-          appendFileSync(join5(tmpdir3(), "forge-perm-probe.log"), `${new Date().toISOString()} ask name=${JSON.stringify(name)} in_status=${output.status} id=${JSON.stringify(input2.id)} type=${JSON.stringify(input2.type)} meta=${JSON.stringify(input2.metadata)}
+          appendFileSync(join6(tmpdir3(), "forge-perm-probe.log"), `${new Date().toISOString()} ask name=${JSON.stringify(name)} in_status=${output.status} id=${JSON.stringify(input2.id)} type=${JSON.stringify(input2.type)} meta=${JSON.stringify(input2.metadata)}
 `);
         } catch {}
       }
@@ -17071,7 +17242,7 @@ var server = async (input, options) => {
       watchdog.markSeen(input2.callID);
       if (process.env.FORGE_WATCHDOG_PROBE) {
         try {
-          appendFileSync(join5(tmpdir3(), "forge-watchdog-probe.log"), `${new Date().toISOString()} mark ${input2.callID} hostpid=${process.pid}
+          appendFileSync(join6(tmpdir3(), "forge-watchdog-probe.log"), `${new Date().toISOString()} mark ${input2.callID} hostpid=${process.pid}
 `);
         } catch {}
       }
@@ -17081,7 +17252,7 @@ var server = async (input, options) => {
         watchdog.untrack(input2.callID);
         if (process.env.FORGE_WATCHDOG_PROBE) {
           try {
-            appendFileSync(join5(tmpdir3(), "forge-watchdog-probe.log"), `${new Date().toISOString()} untrack ${input2.callID}
+            appendFileSync(join6(tmpdir3(), "forge-watchdog-probe.log"), `${new Date().toISOString()} untrack ${input2.callID}
 `);
           } catch {}
         }

package/package.json

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