forgedock 1.7.0 → 1.7.1

package/bin/runner.mjs

@@ -127,6 +127,35 @@ function readOnlySet(values) {
  * simultaneously. Treat it as immutable; mutation attempts throw.
  */
 export const VALID_BACKENDS = readOnlySet(["cli", "api", "auto"]);
+
+export const FORGE_OPENCODE_CAPABILITY_ERROR = "FORGE_OPENCODE_CAPABILITY_ERROR";
+
+/**
+ * Whether the caller is an OpenCode session. The adapter sets this marker on
+ * every shell environment; keeping the predicate small makes all Claude
+ * backend entrypoints agree on the same runtime boundary.
+ */
+export function isOpenCodeRuntime(env = process.env) {
+  return String(env?.FORGE_RUNTIME || "").toLowerCase() === "opencode";
+}
+
+/**
+ * Refuse Claude-backed execution from an OpenCode workflow. OpenCode has its
+ * own Skill/Task execution path; falling through to this runner would create a
+ * competing controller and may consume Claude credentials or quota.
+ */
+export function assertOpenCodeNativeRuntime({
+  env = process.env,
+  operation = "Claude-backed ForgeDock execution",
+} = {}) {
+  if (!isOpenCodeRuntime(env)) return;
+  const error = new Error(
+    `${FORGE_OPENCODE_CAPABILITY_ERROR}: ${operation} is unavailable when FORGE_RUNTIME=opencode. Use native ForgeDock Skill/Task dispatch instead.`,
+  );
+  error.code = FORGE_OPENCODE_CAPABILITY_ERROR;
+  throw error;
+}
+
 // Per-process memoization for isClaudeCliAvailable(), keyed by `cwd` (issue
 // #2011). `runCommand()` calls resolveBackend() — and therefore, for the
 // default "auto" backend, isClaudeCliAvailable() — unconditionally on every
@@ -491,9 +520,10 @@ export function runCliWithStalePathRecovery({
  * API checks verify that a key is configured, not that the key is accepted.
  */
 export function checkExecutionBackend({
-  requested = process.env.FORGEDOCK_BACKEND || "auto",
+  env = process.env,
+  requested = env.FORGEDOCK_BACKEND || "auto",
   cwd = process.cwd(),
-  apiKey = process.env.ANTHROPIC_API_KEY,
+  apiKey = env.ANTHROPIC_API_KEY,
   resolveCliFn = resolveClaudeCliBinary,
   spawnImpl = spawnSync,
   sdkAvailableFn = () => {
@@ -509,6 +539,10 @@ export function checkExecutionBackend({
     return { ready: false, backend: requested, reason: "invalid-backend" };
   }
 
+  if (isOpenCodeRuntime(env)) {
+    return { ready: false, backend: "opencode", reason: "native-opencode-required" };
+  }
+
   if (requested !== "api") {
     const cliPath = resolveCliFn(cwd);
     if (cliPath) {
@@ -606,14 +640,16 @@ export function resolveBackendLadder({
  * @param {object} [opts]
  * @param {string} [opts.requested] - "cli" | "api" | "auto" (default "auto").
  * @param {string} [opts.cwd]       - Working directory for the CLI probe.
+ * @param {object} [opts.env]       - Runtime environment used for capability checks.
  * @returns {"cli"|"api"}
  */
-export function resolveBackend({ requested = "auto", cwd = process.cwd() } = {}) {
+export function resolveBackend({ requested = "auto", cwd = process.cwd(), env = process.env } = {}) {
   if (!VALID_BACKENDS.has(requested)) {
     throw new Error(
       `Invalid backend "${requested}". Must be one of: ${[...VALID_BACKENDS].join(", ")}.`,
     );
   }
+  assertOpenCodeNativeRuntime({ env, operation: "Claude-backed backend resolution" });
   return resolveBackendLadder({
     override: requested === "auto" ? undefined : requested,
     validOverrides: new Set(["cli", "api"]),
@@ -2086,9 +2122,15 @@ export async function runCommand(opts = {}) {
     maxIterations = DEFAULT_MAX_ITERATIONS,
     dryRun = false,
     backend = process.env.FORGEDOCK_BACKEND || "auto",
+    runtimeEnv = process.env,
     logger = console,
   } = opts;
 
+  assertOpenCodeNativeRuntime({
+    env: runtimeEnv,
+    operation: "Claude-backed ForgeDock runner",
+  });
+
   const spec = loadCommandSpec(commandsDir, commandName);
   const systemPrompt = buildSystemPrompt(spec, { repoRoot: cwd });
   // CLI-backend-specific prompt (issue #2019) — see buildCliSystemPrompt's
@@ -2104,10 +2146,10 @@ export async function runCommand(opts = {}) {
   // misbehaving. An explicitly invalid `backend` value DOES throw here —
   // surfacing a bad --backend/FORGEDOCK_BACKEND value immediately, before any
   // work is attempted, rather than silently ignoring it.
-  let resolvedBackend = resolveBackend({ requested: backend, cwd });
+  let resolvedBackend = resolveBackend({ requested: backend, cwd, env: runtimeEnv });
 
   if (resolvedBackend === "cli" && backend === "auto") {
-    const readiness = checkExecutionBackend({ requested: "auto", cwd, apiKey });
+    const readiness = checkExecutionBackend({ requested: "auto", cwd, apiKey, env: runtimeEnv });
     if (readiness.backend === "api") resolvedBackend = "api";
   }
 

package/commands/orchestrate/phase-3-dependency.md

@@ -1145,8 +1145,15 @@ if [ -n "${OPENCODE_SESSION_ID:-}" ] || [ -n "${OPENCODE_PID:-}" ] || [ -n "${OP
 fi
 
 if [ "$FORGE_RUNTIME" = "opencode" ]; then
-  echo "OpenCode runtime detected: native task dispatch selected; Claude background dispatch is not required."
-  BACKGROUND_DISPATCH_ENABLED=false
+  echo "OpenCode runtime detected: native task dispatch selected."
+  # ForgeDock's OpenCode plugin opts into background task events by default so
+  # each completed DAG node can wake this parent without a wave barrier.
+  if [ "${OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS:-true}" = "false" ]; then
+    echo "OpenCode background subagents explicitly disabled: orchestration is degraded to foreground task dispatch."
+    BACKGROUND_DISPATCH_ENABLED=false
+  else
+    BACKGROUND_DISPATCH_ENABLED=true
+  fi
 fi
 
 # Feature gate check — run once before Phase 4 dispatch begins
@@ -1176,13 +1183,23 @@ fi
 
 When `FORGE_RUNTIME=opencode` (or an OpenCode runtime marker is present), do not
 interpret a missing `claude` executable as an environment failure. The Phase 4
-dispatcher must use OpenCode's inline continuation contract instead of the
-Claude `Agent(...)` fallback. Claude remains the default when no runtime marker
-is present, preserving the existing Claude behavior.
-
-**When `BACKGROUND_DISPATCH_ENABLED=false`**: fall back to the current streaming dispatch behavior — `run_in_background=true` is still set on each `Agent()` call (existing behavior, already correct), but treat completions as synchronous and do not rely on `agent_completed` notifications. Poll issue labels for terminal state instead.
-
-**When `BACKGROUND_DISPATCH_ENABLED=true`**: use `run_in_background=true` (already in the Step 4A Agent() template) and react to `agent_completed` notifications as documented in Step 4B. Do NOT poll.
+dispatcher must use OpenCode's native `task` contract instead of the Claude
+`Agent(...)` fallback. With background subagents enabled, each task is launched
+with `background=true` and its injected task-result event immediately drives
+predecessor classification and newly-ready dispatch. Claude remains the default
+when no runtime marker is present, preserving the existing Claude behavior.
+
+**When `BACKGROUND_DISPATCH_ENABLED=false`**: Claude falls back to its existing
+synchronous/polling behavior. OpenCode reaches this branch only after an
+explicit `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=false`; use independent
+foreground `task` calls where the host can execute them concurrently, and
+report that per-completion streaming is unavailable. Do not use Claude's
+`Agent(...)` fallback and do not claim the event-driven DAG guarantee.
+
+**When `BACKGROUND_DISPATCH_ENABLED=true`**: Claude uses
+`run_in_background=true` and reacts to `agent_completed` notifications. OpenCode
+uses `task(..., background=true)` and reacts to each injected task-result event.
+Do NOT poll or wait for a whole wave in either enabled path.
 
 ### Orchestrator state reconstruction on wake / after compaction
 

package/commands/orchestrate/phase-4-execution.md

@@ -416,6 +416,9 @@ declare -A AGENT_ISSUE_MAP
 # this map to identify which issue a background-Bash completion notification belongs to,
 # the same role AGENT_ISSUE_MAP plays for Agent-tool `agent_completed` notifications.
 declare -A ENGINE_DISPATCH_MAP
+# OpenCode native task equivalent of ENGINE_DISPATCH_MAP. Keys are issue numbers;
+# values are the session ids returned by task(background=true).
+declare -A OPENCODE_DISPATCH_MAP
 
 # Same-file current-state brief forwarding (forge#1860). Populated by the core streaming
 # dispatch loop below (Step 4B) whenever a Layer 1/2/3 structural predecessor edge (see
@@ -556,10 +559,33 @@ and continue until it reaches
 `workflow:merged`, `workflow:invalid`, `needs-human`, or
 `workflow:awaiting-merge`.
 
+The native call is asynchronous and must be issued once per issue in
+`DISPATCH_NOW`, in the same assistant message where the batch is dispatched:
+
+```
+task(
+  description="Work on {PROJECT_PREFIX}#{NUMBER}",
+  subagent_type="general",
+  background=true,
+  prompt="Use the same Phase 4A work-on template below. Invoke Skill(skill='work-on', args='{PROJECT_PREFIX}{NUMBER} --under-orchestration') and continue until a terminal workflow state."
+)
+```
+
+Capture the returned `<task id="..." state="running">` id in
+`OPENCODE_DISPATCH_MAP[{NUMBER}]`. `background=true` is required for streaming
+DAG behavior; a foreground task makes the orchestrator wait for that issue and
+reintroduces a wave barrier. The ForgeDock OpenCode plugin opts into
+`OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true` by default. An explicit
+`OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=false` is a supported degraded mode,
+but it must be reported as non-streaming rather than treated as equivalent to
+Claude background dispatch. Do not wait for the slowest sibling before handling
+an earlier task-result event.
+
 ```bash
 if [ "${FORGE_RUNTIME:-}" = "opencode" ]; then
   echo "OpenCode native task dispatch selected — load commands/work-on.md for each ready issue."
   echo "Do not call forgedock run-issue or the Claude Agent(...) fallback in this branch."
+  echo "Use task(subagent_type=general, background=true) once per ready issue and process each task-result event immediately."
   echo "If native task dispatch cannot run, post FORGE:OPENCODE_BLOCKED with the missing capability and add needs-human."
 fi
 ```
@@ -567,6 +593,13 @@ fi
 This branch is additive. When OpenCode is not selected, continue through the
 existing engine-first and Claude Agent-spawn paths below without modification.
 
+The generated OpenCode plugin is an executable boundary, not just prompt
+guidance: its `tool.execute.before` hook rejects `claude`, `forgedock
+run-issue`, `npx forgedock run-issue`, and recursive `opencode run` shell
+commands with `FORGE_OPENCODE_CAPABILITY_ERROR`. If a native Skill or Task is
+unavailable, stop with that bounded error and preserve the GitHub label state;
+never compensate by starting a second controller or the Claude-backed engine.
+
 **CRITICAL — never background via shell `&`/`wait`** (fixed forge#2466): A single `forgedock run-issue` invocation drives an issue through investigate → build → review → close and routinely runs 30+ minutes. Backgrounding the process at the *shell* level (`cmd &` … `wait`) does not escape the Bash tool's own per-invocation ceiling — `wait` is itself the foreground command the tool watches, and it blocks for the combined duration of every process in the chunk. This made engine-first dispatch effectively dead code: any chunk running longer than the ceiling was always killed, so every run silently fell through to the Agent-spawn fallback below. The fix: dispatch each `forgedock run-issue` invocation as its **own `Bash` tool call with `run_in_background=true`** — the harness's native "start it, don't wait, notify me on completion" primitive — never with shell-level `&`/`wait`. This is exactly the same async model the Agent-spawn-fallback path already uses (and Step 4B's notification-driven completion loop already expects), so one monitoring loop now covers both dispatch styles.
 
 ```bash
@@ -687,7 +720,13 @@ ENGINE_DISPATCH_MAP[{NUM}] = <task_id returned by Bash(run_in_background=true, .
 
 If `DISPATCH_NOW` is empty (headroom is 0), do not dispatch any issues this cycle — wait for the next completion notification, exactly like the Agent-spawn path.
 
-**Agent-spawn path (fallback when forgedock CLI unavailable)**: When `FORGEDOCK_AVAILABLE=false`, spawn Agent sub-agents per issue using the template below. This preserves engine state via the SubagentStop hook even without the CLI.
+**Agent-spawn path (Claude fallback when forgedock CLI unavailable)**: When `FORGEDOCK_AVAILABLE=false` and the runtime is not OpenCode, spawn Agent sub-agents per issue using the template below. This preserves engine state via the SubagentStop hook even without the CLI.
+
+When the runtime is OpenCode, skip this Claude-only `Agent(...)` path entirely.
+Use the native `task` call above for initial, newly-ready, remediation, and
+stall-resume dispatches. Translate every later `Agent(...)` reference in this
+phase to `task(...)` with `subagent_type="general"`; preserve `background=true`
+and use `task_id=OPENCODE_DISPATCH_MAP[{NUMBER}]` when resuming a child.
 
 **REMINDER: You MUST use the template below verbatim when on the Agent-spawn fallback path. Only fill in `{VARIABLES}`. Do NOT rewrite the agent prompt. Do NOT write custom implementation instructions. The agent MUST invoke `/work-on` via the Skill tool — this is the HARD RULE from the top of this file.**
 
@@ -917,9 +956,9 @@ If `DISPATCH_NOW` is empty (headroom is 0), do not spawn any agents this cycle
 
 ### Step 4B: Monitor completions and dispatch newly ready issues
 
-You will be automatically notified when each background agent completes — or, for an engine-first dispatch (Step 4A, `FORGEDOCK_AVAILABLE=true`), when a backgrounded `Bash(run_in_background=true, command="forgedock run-issue ...")` call completes. Both are the same underlying "background task finished" notification the harness delivers; treat them identically for the purposes of this step. **Do NOT use `sleep` loops to poll for completion.** Instead, wait for the automatic notification. When one arrives, look up which issue it belongs to — `AGENT_ISSUE_MAP` for an `agent_completed` notification, `ENGINE_DISPATCH_MAP` (fixed forge#2466) for a background-Bash notification from the engine-first path — and immediately process it exactly the same way regardless of which map resolved it; every check below (`classify_predecessor_state()`, dependent dispatch, stall/staging checks) keys off GitHub labels/state, not which dispatch mechanism produced them. **Fallback**: if a runtime ever fails to deliver a background-Bash completion notification, poll `gh issue view --json labels` for the in-flight engine-dispatched issue's workflow label instead of blocking — the same degrade-gracefully behavior already used when `BACKGROUND_DISPATCH_ENABLED=false` for the Agent-spawn path (see `phase-3-dependency.md` → Background Dispatch Mode).
+You will be automatically notified when each background agent completes — or, for an engine-first dispatch (Step 4A, `FORGEDOCK_AVAILABLE=true`), when a backgrounded `Bash(run_in_background=true, command="forgedock run-issue ...")` call completes. In OpenCode, a native background `task` first returns a `state="running"` result and later injects a synthetic `<task id="..." state="completed">` or `state="error"` result into this same parent session. The later result is the completion event; the initial running result is not completion. Both Claude notifications and OpenCode task-result events must trigger the same per-issue handling immediately. **Do NOT use `sleep` loops, wait for the slowest sibling, or poll before processing an event.** When one arrives, look up which issue it belongs to — `AGENT_ISSUE_MAP` for a Claude `agent_completed` notification, `ENGINE_DISPATCH_MAP` for a background-Bash notification, or `OPENCODE_DISPATCH_MAP` for an OpenCode task result — and immediately process it exactly the same way regardless of which map resolved it; every check below (`classify_predecessor_state()`, dependent dispatch, stall/staging checks) keys off GitHub labels/state, not which dispatch mechanism produced them. **Fallback**: if a runtime ever fails to deliver a background completion notification, use the documented label-state recovery path, but do not convert the normal OpenCode path to foreground tasks or a wave barrier.
 
-**Concurrency slot release (MANDATORY — first action on every completion)** <!-- Added: forge#1912 -->: The instant a completion notification arrives — `agent_completed`, or a background-Bash completion for an engine-dispatched issue — decrement `ACTIVE_DISPATCH_COUNT` by 1 — a worker slot has just freed, regardless of what terminal state the issue ended up in. Do this before any stall-recovery/resume logic below. If that agent is then resumed or fallback-dispatched (item 2 below, or Step 4B.5's stall recovery) because it stalled mid-pipeline rather than truly finishing, re-increment `ACTIVE_DISPATCH_COUNT` when the `Agent(resume=...)` (or, per item 2b below, the fresh `Agent(...)` fallback dispatch) call is issued — either re-occupies a worker slot exactly like a fresh dispatch does. (Step 4B.5's TIME-BASED hang detector — an agent that never completes at all, as opposed to one that completes at `workflow:engine-error` — remains `Agent(resume=...)`-specific and out of scope for this fix: an engine-dispatched issue that silently hangs still surfaces only via the standard stall-detection alert, and `forgedock resume-stalled` remains available as a separate manual/scripted recovery path for that case. The completion-triggered case — an engine-dispatched issue that DOES complete, at `workflow:engine-error` with empty committed state — is now auto-fallen-back to Agent-spawn by item 2b below, fixed forge#2743.)
+**Concurrency slot release (MANDATORY — first action on every completion)** <!-- Added: forge#1912 -->: The instant a completion notification arrives — `agent_completed`, a background-Bash completion, or an OpenCode `task` result with `state="completed"`/`state="error"` — decrement `ACTIVE_DISPATCH_COUNT` by 1 — a worker slot has just freed, regardless of what terminal state the issue ended up in. Do this before any stall-recovery/resume logic below. If that agent is then resumed or fallback-dispatched (item 2 below, or Step 4B.5's stall recovery) because it stalled mid-pipeline rather than truly finishing, re-increment `ACTIVE_DISPATCH_COUNT` when the `Agent(resume=...)` or OpenCode `task(task_id=..., background=true)` call is issued — either re-occupies a worker slot exactly like a fresh dispatch does. (Step 4B.5's TIME-BASED hang detector — an agent that never completes at all, as opposed to one that completes at `workflow:engine-error` — remains resume-specific and out of scope for this fix: an engine-dispatched issue that silently hangs still surfaces only via the standard stall-detection alert, and `forgedock resume-stalled` remains available as a separate manual/scripted recovery path for that case. The completion-triggered case — an engine-dispatched issue that DOES complete at `workflow:engine-error` with empty committed state — is still auto-fallen-back by item 2b below, fixed forge#2743.)
 
 **Ordering requirement (MANDATORY — prevents transient over-cap)**: For every agent that completed in this notification batch, finish its terminal-state check and, if applicable, its resume re-increment (items 1-2 below) BEFORE computing `dispatch_headroom` for item 5's newly-ready-issue dispatch. Computing headroom before a to-be-resumed agent's re-increment would let a genuinely-still-running agent's freed slot be double-booked — once by a fresh dispatch, once by the resume itself — transiently exceeding `MAX_CONCURRENT`. Process every completed agent's items 1-2 to a decision (terminal vs. resumed) first; only then compute headroom once for the batch's item 5 dispatch.
 

package/commands/review-pr-agents.md

@@ -19,6 +19,14 @@ the `prompt` argument to whichever tool the orchestrator resolved (`Task(...)` o
 same per-agent isolation and the same requirement that each agent posts structured findings to the PR
 directly (`gh pr comment`) rather than relaying them through the orchestrator's own context.
 
+**OpenCode override**: When `FORGE_RUNTIME=opencode` or an equivalent OpenCode marker is present, the
+orchestrator must set `DISPATCH_TOOL=task` before checking literal Claude tool names. A native task
+argument is shaped as `{ description: "...", prompt: "...", subagent_type: "general"|"explore", background: true }`:
+use `general` for implementation/review and `explore` for read-only discovery. The `Neither tool is
+available` hard stop applies only when lowercase native `task` is genuinely absent; it must not be
+triggered by the absence of `Task` and `Agent` names in an OpenCode session. If native `task` is absent,
+post `FORGE:REVIEW_BLOCKED` and never replace the isolated review with inline work.
+
 <!-- FORGE:PROTOCOL_SOURCE — canonical definition lives in docs/spec/review-protocol.md -->
 
 ---

package/commands/review-pr-staging.md

@@ -23,6 +23,24 @@ Performs comprehensive review of `staging` before merging to `main`. Handles lar
 
 This spec dispatches Bug Hunter and domain review agents via a sub-agent-spawning tool. Different runtimes expose different tools for this — resolve deterministically, once per invocation, and use the same tool for every dispatch call in this run:
 
+### OpenCode Runtime Override
+
+When the workflow is running under OpenCode, resolve the native tool before applying the Claude-specific availability order above:
+
+```bash
+IS_OPENCODE_RUNTIME=false
+if [ "${FORGE_RUNTIME:-}" = "opencode" ] ||
+   [ -n "${OPENCODE_SESSION_ID:-}" ] ||
+   [ -n "${OPENCODE_PID:-}" ] ||
+   [ -n "${OPENCODE:-}" ]; then
+  IS_OPENCODE_RUNTIME=true
+  DISPATCH_TOOL=task
+  DISPATCH_SUBAGENT_TYPE=general
+fi
+```
+
+When `IS_OPENCODE_RUNTIME=true`, lowercase native `task` is the preferred isolated dispatch tool. Do not enter the `Neither tool is available` branch merely because Claude's literal `Task` and `Agent` names are absent. Every native task call must use a top-level `subagent_type`: `general` for implementation/review work and `explore` for read-only discovery (Claude `general-purpose` and `codebase-explorer` map to those values). Use `background: true` for independent reviewers so the parent can process each completion event without a wave barrier. If the native `task` capability itself is absent from the current tool registry, use the existing hard-stop path and post `FORGE:REVIEW_BLOCKED`; never substitute inline review.
+
 1. **If `Task` is available in the current environment**: set `{DISPATCH_TOOL} = Task`. This is the preferred tool — tightest `allowed-tools` scoping. (Identical resolution logic to `/review-pr` Phase 3C — do not diverge.)
 2. **Else if `Agent` is available**: set `{DISPATCH_TOOL} = Agent`. This is the documented fallback, not a degraded path — use it exactly as you would `Task`: one call per selected agent (Bug Hunters in Phase 3, Code Quality in Phase 4, domain agents in Phase 5), same prompt template, `subagent_type: "general-purpose"` (or the closest equivalent the environment offers), same requirement that each agent posts its own findings directly to the PR via `gh pr comment`. Isolation and fresh-context review are preserved either way.
 3. **Neither tool is available**: this is a genuine setup defect, not a routing decision — HARD STOP, post a PR/issue comment explaining that no sub-agent dispatch tool is available, add `needs-human`, and exit without posting a verdict. Do NOT fall back to reviewing inline in the orchestrator's own context.

package/commands/review-pr.md

@@ -33,6 +33,24 @@ allowed-tools: Task, Agent, Bash, Read, Grep, Glob, WebFetch, Skill
 
 This spec dispatches domain review agents via a sub-agent-spawning tool. Different runtimes expose different tools for this — resolve deterministically, once per invocation, and use the same tool for every dispatch call in this run:
 
+### OpenCode Runtime Override
+
+When the workflow is running under OpenCode, resolve the native tool before applying the Claude-specific availability order above:
+
+```bash
+IS_OPENCODE_RUNTIME=false
+if [ "${FORGE_RUNTIME:-}" = "opencode" ] ||
+   [ -n "${OPENCODE_SESSION_ID:-}" ] ||
+   [ -n "${OPENCODE_PID:-}" ] ||
+   [ -n "${OPENCODE:-}" ]; then
+  IS_OPENCODE_RUNTIME=true
+  DISPATCH_TOOL=task
+  DISPATCH_SUBAGENT_TYPE=general
+fi
+```
+
+When `IS_OPENCODE_RUNTIME=true`, lowercase native `task` is the preferred isolated dispatch tool. Do not enter the `Neither tool is available` branch merely because Claude's literal `Task` and `Agent` names are absent. Every native task call must use a top-level `subagent_type`: `general` for implementation/review work and `explore` for read-only discovery (Claude `general-purpose` and `codebase-explorer` map to those values). Use `background: true` for independent reviewers so the parent can process each completion event without a wave barrier. If the native `task` capability itself is absent from the current tool registry, use the existing hard-stop path and post `FORGE:REVIEW_BLOCKED`; never substitute inline review.
+
 1. **If `Task` is available in the current environment**: set `{DISPATCH_TOOL} = Task`. This is the preferred tool — tightest `allowed-tools` scoping.
 2. **Else if `Agent` is available**: set `{DISPATCH_TOOL} = Agent`. This is the documented fallback, not a degraded path — use it exactly as you would `Task`: one call per selected domain agent, same prompt template, `subagent_type: "general-purpose"` (or the closest equivalent the environment offers), same requirement that each agent posts its own findings directly to the PR via `gh pr comment`. Isolation and fresh-context review are preserved either way.
 3. **Neither tool is available**: this is a genuine setup defect, not a routing decision — HARD STOP, post a PR/issue comment explaining that no sub-agent dispatch tool is available, add `needs-human`, and exit without posting a verdict. Do NOT fall back to reviewing inline in the orchestrator's own context — inline self-review is strictly weaker than an isolated fresh-context reviewer and is never a substitute for a missing dispatch tool.
@@ -1520,7 +1538,7 @@ The `protocols.md` file contains the Evidence-Based Review Protocol, Structured
 6. Substitute code index slice: `[INDEX_SLICE]` → the matching `$INDEX_SLICE_{DOMAIN}` variable for this agent (e.g., `$INDEX_SLICE_AUTH` for the auth agent). Agents MUST query index data first; fall back to grep only when index slice is empty or unavailable.
 7. Substitute per-agent diff slice: `[DOMAIN_DIFF_SLICE]` → the matching `$DIFF_SLICE_*` variable (e.g., `$DIFF_SLICE_AUTH` for the auth agent, `$DIFF_SLICE_SECURITY` for the security agent). This replaces any `gh pr diff [PR_NUMBER]` call inside the agent template — the agent works from the pre-computed slice, not the full changeset.
 8. If Phase 2.5 found broken assumptions, append them to the agent's prompt as "Pre-found integration issues to verify"
-9. Launch via the resolved `{DISPATCH_TOOL}` (see Sub-Agent Dispatch Tool Resolution above) with `model: "{SUBAGENT_MODEL}"` (forge.yaml `agents.subagent_model`, else `agents.default_model`, else `"sonnet"`; fallback `"opus"` if rate-limited)
+9. Launch via the resolved `{DISPATCH_TOOL}` (see Sub-Agent Dispatch Tool Resolution above) with `model: "{SUBAGENT_MODEL}"` (forge.yaml `agents.subagent_model`, else `agents.default_model`, else `"sonnet"`; fallback `"opus"` if rate-limited). Under OpenCode, emit a top-level `subagent_type: "general"` or `"explore"` in the native `task` argument object and use `background: true` for each independent reviewer.
 
 **CRITICAL**: Launch ALL selected agents in a SINGLE message using multiple `{DISPATCH_TOOL}` calls. Each agent posts findings directly to the PR via `gh pr comment`.
 
@@ -1553,7 +1571,7 @@ gh pr view $ARGUMENTS --json comments --jq '.comments | length'
 gh api repos/{owner}/{repo}/issues/$ARGUMENTS/comments --jq '.[-10:] | .[].body[:100]'
 ```
 
-**Do NOT proceed until ALL launched agent comments are visible on the PR.**
+**Do NOT proceed until ALL launched agent comments are visible on the PR.** Under OpenCode, the initial `task(..., background: true)` result with `state="running"` is not completion; wait for and process each injected `task` result event, then verify the corresponding structured PR comment before continuing.
 
 ---
 

package/docs/CONFIG.md

@@ -927,7 +927,7 @@ The hook entry is registered idempotently: re-installing (`npx forgedock update`
 | Command | Action |
 |---------|--------|
 | `npx forgedock` / `npx forgedock install` | Registers the SessionStart hook (along with installing commands and writing `forge.yaml`) |
-| `npx forgedock update` | Re-registers the hook (relink only — does not touch `forge.yaml`) |
+| `npx forgedock update` | Re-registers the hook when the resolved source can be safely refreshed (relink only — does not touch `forge.yaml`) |
 | `npx forgedock uninstall` | Removes the hook entry from `settings.json` |
 
 ### Opting Out
@@ -948,7 +948,7 @@ See [Per-Directory State Registry](#per-directory-state-registry) below for how
 
 `npx`/`npm` never installs `forgedock` to a stable location on your machine — it resolves to wherever `npx`'s cache (or a global npm install, or a git clone) happens to physically live. Historically, `~/.claude/commands/` and the SessionStart hook's script path were symlinked **directly** from that ephemeral location. When npm/npx (or the OS) later evicted its cache, those symlinks silently dangled — Claude Code sessions stopped getting ForgeDock context with no error shown.
 
-As of this feature, every `npx forgedock` (or `npx forgedock update`) run copies ForgeDock's own installable payload into a stable, version-independent home:
+For npm/npx sources, every `npx forgedock` (or `npx forgedock update`) run copies ForgeDock's own installable payload into a stable, version-independent home:
 
 ```
 ~/.forge/
@@ -968,8 +968,8 @@ As of this feature, every `npx forgedock` (or `npx forgedock update`) run copies
 | `npx forgedock` / `npx forgedock install` | Copies the resolved package's payload into `~/.forge/` (content-compared — unchanged files are never rewritten) before linking commands, then links from `~/.forge/`, not the original source |
 | `npx forgedock init` | Does not touch `~/.forge/` — `init` only writes `forge.yaml`, it never installs commands |
 | `npx forgedock update` (npm/npx install) | Refreshes `~/.forge/` from whatever the currently-resolved package looks like, then relinks |
-| `npx forgedock update` (git-clone install) | **Does not** touch `~/.forge/` at all — see the exemption below |
-| `npx forgedock doctor` | Reports `~/.forge/version` and confirms `~/.forge/{bin,commands,scripts,templates}` exist |
+| `npx forgedock update` (git-clone install) | Updates and relinks a `main` checkout; a non-main checkout is left untouched and gets actionable guidance because the current source must remain the source used after the command returns |
+| `npx forgedock doctor` | Reports the effective source path, version, and git branch, then reports `~/.forge/version` and confirms `~/.forge/{bin,commands,scripts,templates}` for npm installs |
 
 The copy is idempotent: files whose content is already byte-identical are never rewritten, so steady-state re-runs are fast and don't generate false "updated" noise.
 
@@ -979,6 +979,7 @@ If you run ForgeDock from a git clone (or a git worktree) of the repo itself —
 
 - `~/.claude/commands/` continues to symlink directly from the clone, exactly as before this feature.
 - `~/.forge/{bin,commands,scripts,templates}` correctly does **not** exist for this install mode — `npx forgedock doctor` treats that absence as healthy, not a warning.
+- `npx forgedock update` never switches a non-main checkout to `main` and then restores it. That transient update would leave the next invocation running the old branch source, so the command reports the effective path, branch, and version and tells you to run from a main checkout instead.
 
 ### Not the Same as `~/.forge/{runs,index}`
 
@@ -1086,7 +1087,7 @@ The directory (`~/.forge/`) is created automatically on first write with `mkdir(
 ### When It's Written
 
 - After every successful `npx forgedock install` (end of the onboarding journey, right after the "Forged." celebration screen).
-- After every `npx forgedock update` — both the git-clone branch (fast-forward pull) and the npm branch (version-check advisory) route through the same repair step (`relinkAndHint()`), so the receipt is refreshed either way.
+- After every successful `npx forgedock update` — the main git-clone branch and npm branch route through the same repair step (`relinkAndHint()`), so the receipt is refreshed either way. A non-main git-clone advisory intentionally does not relink or rewrite the receipt.
 
 The write is best-effort and never blocks or fails the install/update it records: any error (permission denied, disk full, unusual `FORGE_HOME` layout) degrades silently to a no-op, matching the fail-open contract already used by the command-manifest and hook-registration steps.
 

package/docs/OPENCODE.md

@@ -19,12 +19,12 @@ For the optional command tier:
 npx forgedock opencode install --extras
 ```
 
-Restart OpenCode after install or update. OpenCode loads commands and plugins
-at startup.
+Restart OpenCode after install or update. OpenCode loads commands, skills, and
+plugins at startup.
 
-The installer does not edit `opencode.json` or `opencode.jsonc`. It writes only
-ForgeDock-owned files under OpenCode's config directory and records them in
-`forgedock/manifest.json` for safe updates and removal.
+The native adapter does not add or modify user-owned OpenCode settings. It
+writes only ForgeDock-owned files under OpenCode's config directory and records
+them in `forgedock/manifest.json` for safe updates and removal.
 
 ## Usage
 
@@ -62,9 +62,29 @@ The generated plugin has no prompt text. It:
 - injects `FORGE_HOME` into OpenCode shell environments;
 - defaults `subagent_depth` to 2 when the user has not configured it, while
   preserving explicit lower limits;
+- grants the built-in `general` subagent permission to invoke native `task`
+  unless the user explicitly configured a task permission;
+- opts into OpenCode background subagents by default so each completed issue can
+  wake the parent orchestrator independently; set
+  `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=false` to opt out;
 - selects Git Bash on Windows only when the user has not explicitly configured
   an OpenCode shell, because the shared workflows and helper scripts use Bash.
 
+The adapter also registers every eligible ForgeDock workflow as a native
+OpenCode skill. Top-level and nested source paths are normalized to valid
+hyphenated skill names while the wrapper continues to point at the authoritative
+source file:
+
+```text
+commands/work-on.md             -> skills/work-on/SKILL.md
+commands/work-on/investigate.md -> skills/work-on-investigate/SKILL.md
+commands/review-pr.md           -> skills/review-pr/SKILL.md
+```
+
+The wrapper is intentionally thin. It carries the workflow's `name` and
+`description` frontmatter, preserves the current-context arguments, and loads
+only the referenced `commands/**/*.md` spec.
+
 OpenCode's provider configuration remains entirely user-owned. ForgeDock does
 not require Anthropic when invoked through OpenCode; any provider and model
 supported by the user's OpenCode configuration can execute the commands.
@@ -74,19 +94,45 @@ supported by the user's OpenCode configuration can execute the commands.
 The adapter follows these rules:
 
 - No global ForgeDock `instructions` entry.
-- No generated skill for every source file. Large skill catalogs add metadata
-  to every session even when ForgeDock is unused.
-- Only top-level user entry commands are registered.
+- Top-level user entry commands are registered under `/forge/*`.
+- Every eligible workflow is registered as a native skill so nested
+  `Skill(...)` dispatch resolves through OpenCode's `skill` tool instead of
+  filesystem guessing.
 - Nested phase specs are loaded only when their dispatcher reaches them.
 - Task/Agent work uses OpenCode subagents only for the parallelism, isolation,
   or context-pressure cases required by the shared workflow.
+- Orchestration dispatches independent issues with `task(background=true)` and
+  processes each injected task-result event immediately; it does not wait for a
+  wave or the slowest sibling.
 - GitHub state and the durable engine remain the recovery source instead of
   replaying prior prompt context.
 
 The generated adapter preamble is intentionally small. It maps Claude Code's
-in-conversation `Skill(...)` loading to a lazy read of the corresponding shared
-spec. It maps isolated `Task(...)` and permitted `Agent(...)` calls to
-OpenCode's native `task` tool.
+in-conversation `Skill(...)` loading to the normalized native skill name and
+authoritative shared spec. It maps isolated `Task(...)` and permitted
+`Agent(...)` calls to OpenCode's native `task` tool. Before the shared review
+specs evaluate Claude's literal `Task`/`Agent` names, an OpenCode runtime marker
+selects `DISPATCH_TOOL=task`; the absence of those Claude names must not produce
+a false `FORGE:REVIEW_BLOCKED` result.
+
+Every isolated review dispatch uses the explicit native argument shape. Every
+native task call must include the schema-required `subagent_type` at the top
+level alongside its `description` and `prompt`:
+
+```js
+{ description: "...", prompt: "...", subagent_type: "general", background: true }
+```
+
+Implementation and review work uses `general`; read-only discovery uses
+`explore`. Claude `general-purpose` maps to `general` and
+`codebase-explorer` maps to `explore`. When a source task omits its type, the
+generated adapter safely defaults it to `general`; unsupported types stop with
+`FORGE_OPENCODE_CAPABILITY_ERROR` instead of reaching schema validation.
+If the native `task` capability itself is unavailable, the workflow posts
+`FORGE:REVIEW_BLOCKED` and stops rather than falling back to inline review or
+another pipeline controller.
+The generated plugin adds `background: true` unless
+`OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=false` is explicitly set.
 
 `commands/work-on.md` is still a large entry dispatcher and is loaded in full,
 matching the Claude Code path. The adapter prevents additional eager loading,
@@ -102,13 +148,27 @@ npx forgedock opencode install --extras
 npx forgedock opencode uninstall
 ```
 
+`npx forgedock update` also refreshes an existing managed OpenCode adapter,
+including its plugin and generated skills. It preserves the installed core vs.
+`--extras` tier, migrates the sentinel-marked legacy adapter, and does not
+install OpenCode files when no ForgeDock adapter is already registered.
+
 Updates are deterministic and prune stale ForgeDock-owned command files.
 Uninstall removes only files listed in the ownership manifest and still marked
 with a ForgeDock sentinel. User-owned commands, plugins, and files placed in
 the `forgedock/` namespace are never removed; that namespace is pruned only
 when it is empty.
-Install also removes the previous ForgeDock-managed `~/.opencode-forge.md`
-instructions file and its exact legacy config entries when they are present.
+For backward compatibility, install and uninstall may rewrite `opencode.json`
+only to remove legacy entries whose two-key `description` and `template` still
+exactly match one of the definitions emitted by the retired adapter and point to
+the active ForgeDock home (or the home recorded in the ownership manifest during
+uninstall), and the sentinel-marked legacy instructions file is present. It also
+removes references to that managed `~/.opencode-forge.md` instructions file. The
+migration does not rewrite `opencode.jsonc`. User-owned settings and customized commands are preserved;
+definitions with extra keys, edited fields, different
+paths, a missing ownership marker, or ambiguous ownership are left in place. If
+a legacy config cannot be parsed or written, the migration leaves the legacy
+artifacts in place.
 
 ## Locations
 
@@ -117,6 +177,7 @@ Default global location:
 ```text
 ~/.config/opencode/
   commands/forge/*.md
+  skills/<workflow-name>/SKILL.md
   plugins/forgedock.js
   forgedock/manifest.json
 ```
@@ -133,16 +194,25 @@ The separate `forgedock run` and `forgedock run-issue` backend still supports
 only Claude CLI and the Anthropic API. An OpenCode engine backend must be added
 and validated before ForgeDock can claim provider-neutral headless parity.
 
-Claude's `PreToolUse` safety hook has not yet been ported to an OpenCode plugin.
-The shared workflow rules and deterministic scripts still apply, but equivalent
-mechanical enforcement must be implemented and tested before claiming complete
-Claude-runtime safety parity.
-
-OpenCode 1.18.4 keeps background subagents experimental. When they are not
-enabled, the command adapter requires independent foreground tasks to be
-launched concurrently where supported and uses ForgeDock's GitHub-label polling
-fallback. This preserves isolated review contexts but does not yet prove equal
-wall-clock behavior for `/forge/orchestrate`.
+The ForgeDock plugin provides the OpenCode-specific runtime boundary for shell
+and task execution. Its `tool.execute.before` hook rejects Claude-backed and
+recursive ForgeDock controller commands, and normalizes native task arguments
+before execution; the shared workflow rules and deterministic scripts remain
+the source of truth for all other behavior.
+
+OpenCode 1.18.4 keeps background subagents experimental. ForgeDock opts into
+that feature by default because the streaming DAG depends on the parent session
+receiving one completion event per child. A native background task returns a
+`<task id="..." state="running">` marker immediately and later injects a
+`state="completed"` or `state="error"` result into the parent session. The
+orchestrator maps that id to the issue, re-reads GitHub state, and dispatches
+newly unlocked successors in the same response.
+
+If `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=false` is explicitly set,
+ForgeDock uses independent foreground tasks where OpenCode can execute them
+concurrently and labels the run as degraded. Foreground tasks cannot provide
+the same per-completion wake behavior, so this opt-out intentionally restores a
+wave-like fallback rather than silently claiming Claude-equivalent throughput.
 
 Commands that inspect Claude-specific transcripts or Claude installation state
 remain runtime-specific and should not be represented as portable until they
@@ -151,7 +221,10 @@ receive dedicated implementations.
 ## Orchestration Runtime
 
 OpenCode orchestration uses the native OpenCode `task` tool for isolated issue
-work and follows the shared `commands/work-on.md` state machine. It must not
+work and follows the shared `commands/work-on.md` state machine. Each ready
+issue is launched as `task(subagent_type="general", background=true)` and its
+task-result event is treated as the completion notification for that issue. It
+must not
 route through `forgedock run-issue` when that would select the Claude CLI or
 Anthropic API backend. If the host does not expose an OpenCode runtime marker,
 set the runtime explicitly before launching a headless command:
@@ -162,10 +235,25 @@ FORGE_RUNTIME=opencode opencode run --command forge/orchestrate "fast-lane"
 
 Each task re-reads GitHub labels and `FORGE:*` comments after every phase and
 continues until `workflow:merged`, `workflow:invalid`, `needs-human`, or
-`workflow:awaiting-merge`. If native task dispatch is unavailable, post a
+`workflow:awaiting-merge`. The parent orchestrator processes every child
+completion independently, so a completed predecessor can unlock and dispatch
+its successors while unrelated issues continue running. If native task
+dispatch is unavailable, post a
 `FORGE:OPENCODE_BLOCKED` diagnostic naming the missing capability and add
 `needs-human`; do not leave an issue stranded at `workflow:engine-error`.
 
+If a generated command or skill cannot load its authoritative workflow, it must
+stop with an actionable `FORGE_OPENCODE_CAPABILITY_ERROR`. It must not recover
+by invoking `forgedock run-issue`, `npx forgedock run-issue`, or a recursive
+`opencode run`; those paths select a competing controller or Claude-backed
+backend.
+
+The same boundary is enforced below the plugin for direct CLI callers. With
+`FORGE_RUNTIME=opencode`, `forgedock run`, `forgedock run-issue`, and Claude
+backend preflight fail before selecting a provider. The stable error is
+`FORGE_OPENCODE_CAPABILITY_ERROR`; continue by using the registered native
+Skill and Task workflow instead.
+
 This runtime branch is additive. Claude keeps its existing engine and
 background-agent paths, and Codex keeps its installed namespaced skills and
 repo-local adapters.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "Autonomous development pipeline for coding agents. GitHub as institutional memory, with native Claude Code and OpenCode entrypoints.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"