@sorenllm/opencode-forge 0.10.0 → 0.11.1

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 |
 
@@ -405,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
 {
@@ -419,7 +436,7 @@ cascade with a single winning source (never merged):
     "research": {
       "model": "zai-coding-plan/glm-5.3", // exact "provider/model" string
       "thoughtLevel": "low",              // none/low/medium/high/max or a native level name
-      // "prompt": "optional role prompt; built-in research/review defaults exist",
+      // "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
       // "permission": { "bash": "deny" } // optional override; "task" is ALWAYS denied
     },

package/dist/index.js

@@ -15429,6 +15429,24 @@ 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 {
@@ -15439,7 +15457,7 @@ function createForgeConfigLoader(deps) {
     }
   });
   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);
@@ -15458,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`
           }
         ]
       };
@@ -15473,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: [] };
     }
   };
 }
@@ -15609,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;
@@ -15761,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)) {
@@ -16417,12 +16488,12 @@ 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.",
+  "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: 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.",
   "",
-  "Template (JSONC — comments allowed): `model` + `thoughtLevel` are an ATOMIC PAIR — set BOTH to pin the brain and depth (model = exact provider/model identity; thoughtLevel = none/low/medium/high/max or a native level name), or NEITHER for an Auto worker that inherits the parent session's model; exactly one of the two is rejected.",
+  "Template (JSONC — comments allowed): `model` + `thoughtLevel` are an ATOMIC PAIR — set BOTH to pin the brain and depth (model = exact provider/model identity; thoughtLevel = none/low/medium/high/max or a native level name), or NEITHER for an Auto worker that inherits the parent session's model; exactly one of the two is rejected. 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).",
   "{template}",
   "",
   "After the file is saved: NEW agents require a host restart to appear in the task tool; thoughtLevel edits on existing agents apply without restart. Until then, crew stays unavailable."
@@ -16463,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}`,
-        '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(`
+    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", "prompt": "short role description"}}}',
+        "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) — without a prompt, custom ids get a generic one-liner and will not know their job. Newly added agents need a host restart; thoughtLevel edits apply without one."
+      ];
+      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())
@@ -16497,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(`
 `)
     };
@@ -16961,7 +17050,7 @@ var server = async (input, options) => {
       if (!existingCrew || String(existingCrew.template ?? "").startsWith("(forge crew")) {
         const agentIds = Object.keys(loaded.agents);
         const template = agentIds.length > 0 ? crewOrchestrationTemplate(agentIds) : CREW_INIT_TEMPLATE.replaceAll("{paths}", `   - ${forgeConfigPaths({ projectDir: forgeLoaderDir ?? undefined, homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() }).project}
-   - ${forgeConfigPaths({ projectDir: forgeLoaderDir ?? undefined, homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() }).global}`).replaceAll("{template}", JSON.stringify({ agents: { research: { model: "provider/model", thoughtLevel: "low" } } }, null, 2).split(`
+   - ${forgeConfigPaths({ projectDir: forgeLoaderDir ?? undefined, homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() }).global}`).replaceAll("{template}", JSON.stringify({ agents: { research: { model: "provider/model", thoughtLevel: "low", prompt: "short role description — what this agent does" } } }, null, 2).split(`
 `).map((l) => "   " + l).join(`
 `));
         const description = agentIds.length > 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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sorenllm/opencode-forge",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Single general-purpose forge agent for opencode: static worker subagents defined in forge.json (pinned model + thoughtLevel pair, or an Auto worker inheriting the parent model; dispatched through the native task tool — TUI-visible), a plan harness (file-backed plans with approve/close confirmation gates and a hard draft write-ban), a goal harness (autonomous, host-verified objectives), a /crew orchestration command (declared-plan waves with an evidence-checked close gate), a job supervisor (forge_shell with exit-bound completion, idle/success early return, background jobs with poll/log/kill/handoff), and a builtin-shell hang watchdog.",
   "type": "module",
   "main": "./dist/index.js",