create-agdf 0.11.3 → 0.12.0

package/generated/plugins/agdf/skills/gate-check/SKILL.md

@@ -20,6 +20,7 @@ This skill must not create later artefacts such as PRD, SD, TP, CD, CR, QA, or U
 ## Runtime Contract
 Use these focused runtime-contract modules:
 
+- `../../meta/contracts/task-target-resolution.md`
 - `../../meta/contracts/gate-transition.md`
 - `../../meta/contracts/interaction.md`
 - `../../meta/contracts/control-scaffold.md`
@@ -75,6 +76,12 @@ The CLI reports are validators and JSON evidence, not the primary user experienc
 
 Plugin `AGDF_*` environment variables set by the OpenCode `shell.env` hook are convenience only and must not be used as the only proof of activation; host shell-env propagation to spawned tool shells is not guaranteed and is OpenCode-owned, not AGDF-owned. A relative glob or `grep` for `.agdf/control/config.json` must not be used as proof of presence or absence of `.agdf/control/config.json`; an absolute `read` or the canonical CLI probe is required.
 
+## OpenCode Subagent Enforcement Boundary
+
+OpenCode plugin hooks (`tool.execute.before`) do not intercept tool calls from subagents spawned via the `task` tool (anomalyco/opencode issue #5894, PR #36238 open). AGDF enforcement through plugin hooks applies to primary-agent tool calls only; in the subagent path, AGDF governance is auditing-only, not enforcement.
+
+This is a host limitation, not an AGDF-owned defect. Do not claim that AGDF gates are technically enforced in the OpenCode subagent path. Do not route work to a subagent to bypass a primary-agent gate. When subagent work touches gate-relevant files, verify the result through the canonical validator (`doctor --json`, `gate-check --json`) after the subagent returns, not during.
+
 ## Native Interaction Path
 
 `../../meta/contracts/interaction.md` is the complete normative owner for interaction kinds, locale,
@@ -84,12 +91,15 @@ do not restate or infer a surface matrix in this skill.
 
 This skill owns only these operational responsibilities:
 
-1. Select exactly one run and evaluate its current gate.
-2. Confirm that the required durable artefact is present and ready.
-3. Consume the canonical `approval_presentation` verbatim for the selected run, gate and revision.
-4. Present that projection and obtain deliberate input through the contract-selected native or exact-text path.
-5. Revalidate the same run, gate and revision immediately after the response and before persistence.
-6. Persist only a currently valid exact approval through the existing control-state workflow.
+1. Resolve or revalidate the primary task target before selecting repository control state.
+2. Derive repository activation only from the resolved governance target; an evidence source or
+   working directory is not sufficient.
+3. Select exactly one run and evaluate its current gate.
+4. Confirm that the required durable artefact is present and ready.
+5. Consume the canonical `approval_presentation` verbatim for the selected run, gate and revision.
+6. Present that projection and obtain deliberate input through the contract-selected native or exact-text path.
+7. Revalidate the same target, run, gate and revision immediately after the response and before persistence.
+8. Persist only a currently valid exact approval through the existing control-state workflow.
 
 For status, blocked, read-only or rationale interactions, consume the canonical
 `status_presentation.markdown` verbatim and apply the locale contract without asking for approval.
@@ -156,18 +166,30 @@ Use what is available:
 If a status is not explicit, do not assume it is satisfied.
 
 ## Workflow
-1. Check exact approvals.
-2. Check artefact status.
-3. Determine the earliest blocking user gate or internal mandatory step.
-4. Derive allowed and forbidden outputs.
-5. Name the exact missing approval, if any.
-6. If consent was only implicit, say it is not yet approval and provide the exact formula.
-7. Ensure the next step follows the gate transition table. In particular, never jump from `Approval: UR` to implementation.
-8. Treat a generic "start", "continue" or "leg los" request as a request to perform only the current next allowed action.
-9. After Brownfield Review, choose the smallest safe process path before creating later artefacts.
-10. If the selected path is not visibly recorded with scope reason and evidence, keep the run at `Mode/Slice Decision`.
-11. When `.agdf/control/` is missing or incomplete, make the next allowed artefact action explicit. For a fresh request, that means draft the minimal UR in the response, then request `Approval: UR`. Do not write a full control scaffold unless durable control state was explicitly requested or is already the repository's live AGDF working state.
-12. If branch, workspace and durable artefacts disagree, do not choose a scope silently; report the ambiguity and ask for the smallest clarifying gate action.
+1. Resolve or revalidate the primary target through `task-target-resolution.md`.
+2. If resolution is unresolved, consume the canonical target orientation, request only its
+   clarification/recovery action and stop before repository activation, gate evaluation or mutation.
+3. Derive the governance target from the primary target; never from `cwd` or an evidence source alone.
+4. Check exact approvals.
+5. Check artefact status.
+6. Determine the earliest blocking user gate or internal mandatory step.
+7. Derive allowed and forbidden outputs.
+8. Name the exact missing approval, if any.
+9. If consent was only implicit, say it is not yet approval and provide the exact formula.
+10. Ensure the next step follows the gate transition table. In particular, never jump from `Approval: UR` to implementation.
+11. Treat a generic "start", "continue" or "leg los" request as a request to perform only the current next allowed action.
+12. After Brownfield Review, choose the smallest safe process path before creating later artefacts.
+13. If the selected path is not visibly recorded with scope reason and evidence, keep the run at `Mode/Slice Decision`.
+14. When `.agdf/control/` is missing or incomplete, make the next allowed artefact action explicit. For a fresh request, that means draft the minimal UR in the response, then request `Approval: UR`. Do not write a full control scaffold unless durable control state was explicitly requested or is already the repository's live AGDF working state.
+15. If branch, workspace and durable artefacts disagree, do not choose a scope silently; report the ambiguity and ask for the smallest clarifying gate action.
+
+### Task Target Orientation
+
+When target/context separation is material, the target changed, or resolution is unresolved, consume
+`task_target_orientation.markdown` verbatim from `renderTaskTargetOrientation` in
+`../../meta/contracts/interaction.md`. Do not reconstruct its fields or maintain a skill-local target
+template. If the renderer returns `null`, fail closed to target clarification and do not proceed to
+repository activation, Scope Classification or gate evaluation.
 
 ### Scope Classification Output
 When this skill classifies a fresh scope as ungated (Quick Task or Trivial Change Boundary), consume

package/lib/cli/application.js

@@ -115,9 +115,19 @@ function createHandlers({ io, env, exec, prepare }) {
         const result = runLifecyclePhase("plugin_operation", () => installOpenCodeGlobalPlugin(configDir));
         runLifecyclePhase("global_surface", () => installOpenCodeGlobalSurface(configDir));
         const report = runLifecyclePhase("verification", () => evaluateOpenCodeStatus(options.dir, configDir, result.transition));
+        const alignmentHealthy = ["already_matching", "aligned"].includes(result.sdk_alignment.status);
         const verificationHealthy = report.status === "configured"
           && report.package.version_status === "current"
-          && report.global_native_surface.complete;
+          && report.global_native_surface.complete
+          && report.experimental_hooks.aggregate === "declared_supported"
+          && report.host_sdk_version.status === "matching"
+          && alignmentHealthy;
+        const nextAction = verificationHealthy
+          ? globalInstallRestartAction(options.target)
+          : {
+              kind: "recovery",
+              text: `Retry the OpenCode installation to align @opencode-ai/plugin to ${result.sdk_alignment.target_version || "the exact host version"}; observed SDK: ${result.sdk_alignment.installed_version || "unknown"}.`,
+            };
         printLifecycleResult(createLifecycleResult({
           operation: result.transition.status === "updated" ? "update" : "install",
           result: verificationHealthy ? "success" : "partial",
@@ -130,10 +140,26 @@ function createHandlers({ io, env, exec, prepare }) {
             status: report.package.version_status === "current" ? "verified" : "unknown",
             transition: result.transition.status,
           },
-          verification: { status: verificationHealthy ? "healthy" : "degraded", evidence: [report.global_config.path, report.global_native_surface.path] },
+          verification: {
+            status: verificationHealthy ? "healthy" : "degraded",
+            evidence: [
+              report.global_config.path,
+              report.global_native_surface.path,
+              `opencode_host=${report.host.installed_version || "unknown"}`,
+              `plugin_sdk=${report.plugin_sdk.installed_version || "unknown"}`,
+              `experimental_hooks=${report.experimental_hooks.aggregate}`,
+              `host_sdk_version=${report.host_sdk_version.status};policy=${report.host_sdk_version.policy}`,
+              `sdk_alignment=${result.sdk_alignment.status};target=${result.sdk_alignment.target_version || "unknown"};installed=${result.sdk_alignment.installed_version || "unknown"}`,
+            ],
+          },
           restart: { required: true, reason: "host_reload" },
-          next_action: globalInstallRestartAction(options.target),
+          next_action: nextAction,
         }), { json: options.json, io });
+        if (!options.json) {
+          io.log(`OpenCode host / plugin SDK: ${report.host.installed_version || "unknown"} / ${report.plugin_sdk.installed_version || "unknown"} (${report.host_sdk_version.status}; ${report.host_sdk_version.policy})`);
+          io.log(`Plugin SDK alignment: ${result.sdk_alignment.status} (target ${result.sdk_alignment.target_version || "unknown"}; installed ${result.sdk_alignment.installed_version || "unknown"})`);
+          io.log(`Experimental hook declarations: ${report.experimental_hooks.aggregate} (SDK declaration evidence; live invocation not observed)`);
+        }
         return verificationHealthy ? 0 : 1;
       } catch (error) {
         printInstallFailure(options.target, error, options, io);

package/lib/cli/command-registry.js

@@ -27,8 +27,8 @@ export const commandRegistry = Object.freeze([
   command("gate-check", { local: [" --approval-envelope", " --json"], scaffold: [""], legacy: [" --json"] }),
   command("delivery-map", { local: [" --json"], scaffold: [""] }),
   command("delivery-path-search", {
-    local: [" --surface codex --json", " --surface claude --json"],
-    scaffold: [" --surface codex", " --surface claude"],
+    local: [" --surface codex --json", " --surface claude --json", " --surface opencode --json"],
+    scaffold: [" --surface codex", " --surface claude", " --surface opencode"],
   }),
   command("run-create", { local: [" --run <run_id>"] }),
   command("run-migrate", { local: [" [--run <run_id>]"] }),

package/lib/cli/delivery-path-search-command.js

@@ -3,6 +3,7 @@ import { searchInputFromControl } from '../delivery-path-search/state-adapter.js
 import { runDeliveryPathSearch } from '../delivery-path-search/search-engine.js';
 import { codexEvaluator } from '../delivery-path-search/evaluators/codex.js';
 import { claudeEvaluator } from '../delivery-path-search/evaluators/claude.js';
+import { openCodeEvaluator, preflightOpenCodeEvaluator } from '../delivery-path-search/evaluators/opencode.js';
 import { fixtureEvaluator } from '../delivery-path-search/evaluators/protocol.js';
 import { codexGenerator } from '../delivery-path-search/generators/codex.js';
 import { claudeGenerator } from '../delivery-path-search/generators/claude.js';
@@ -10,12 +11,56 @@ import { fixtureGenerator } from '../delivery-path-search/generators/protocol.js
 import { enforcementForSurface } from '../delivery-path-search/surfaces/capabilities.js';
 import { persistSearchResult } from '../delivery-path-search/persistence.js';
 
-export async function executeDeliveryPathSearch(options, io = console) {
+function unavailableOpenCodeResult({ options, preflight, input = null, error = null }) {
+  const mutation = error?.code === "OPENCODE_EVALUATOR_MUTATION_DETECTED";
+  const attempted = Boolean(input);
+  const nextAction = mutation
+    ? "Investigate and revert the detected repository mutation before any evaluator fallback or retry."
+    : "Repair the reported OpenCode capability and retry, or use the existing instruction-only Delivery Path Search workflow.";
+  return {
+    contract_version: "1",
+    surface: "opencode",
+    scope_key: input?.scope_key ?? options.runId ?? null,
+    current_gate: input?.current_gate ?? null,
+    status: mutation ? "evaluator_error" : "evaluator_unavailable",
+    recommendation: null,
+    enforcement: enforcementForSurface("opencode"),
+    evaluator: {
+      name: "opencode",
+      preflight: preflight?.code ?? "not_run",
+      failure_code: error?.code ?? preflight?.code,
+      detail: error?.message ?? preflight?.detail,
+      evidence: preflight?.evidence ?? [],
+    },
+    executable_evaluator: {
+      attempted,
+      preflight: preflight?.status ?? "failed",
+      failure_code: error?.code ?? preflight?.code,
+      evidence: preflight?.evidence ?? [],
+    },
+    stopping_reason: mutation ? "opencode_mutation_detected" : attempted ? "opencode_evaluator_failed" : "opencode_preflight_failed",
+    next_action: nextAction,
+    next_gate_action: nextAction,
+  };
+}
+
+export async function executeDeliveryPathSearch(options, io = console, dependencies = {}) {
   const fixture = options.fixture ? JSON.parse(readFileSync(options.fixture, "utf8")) : null;
-  const enforcement = fixture?.input?.enforcement ?? enforcementForSurface(options.surface);
+  const preflight = !fixture && options.surface === "opencode"
+    ? (dependencies.preflightOpenCodeEvaluator ?? preflightOpenCodeEvaluator)({ cwd: options.dir })
+    : null;
+  if (preflight?.status === "failed") {
+    const result = unavailableOpenCodeResult({ options, preflight });
+    printDeliveryPathSearchResult(result, options, io);
+    return result;
+  }
+  const enforcement = fixture?.input?.enforcement
+    ?? (preflight
+      ? enforcementForSurface("opencode", preflight.evidence, { preflight })
+      : enforcementForSurface(options.surface));
   const fixtureGeneration = fixture?.generator_response;
   const generationEnabled = Boolean(fixtureGeneration || options.generateCandidates);
-  const baseInput = fixture?.input ?? searchInputFromControl(options.dir, {
+  const baseInput = fixture?.input ?? (dependencies.searchInputFromControl ?? searchInputFromControl)(options.dir, {
     scopeKey: options.runId,
     enforcement,
     generation: generationEnabled ? {
@@ -41,9 +86,11 @@ export async function executeDeliveryPathSearch(options, io = console) {
       ? codexEvaluator({ cwd: options.dir, model: options.model })
       : options.surface === "claude"
         ? claudeEvaluator({ cwd: options.dir, model: options.model })
-        : null;
+        : options.surface === "opencode"
+          ? (dependencies.openCodeEvaluator ?? openCodeEvaluator)({ cwd: options.dir, model: options.model, preflight })
+          : null;
   if (!evaluator) {
-    throw new Error(`${options.surface} has no executable evaluator in this release. Codex and Claude are the reference adapters; --fixture is available for deterministic contract testing.`);
+    throw new Error(`${options.surface} has no executable evaluator in this release. Codex, Claude and preflight-qualified OpenCode are the executable adapters; --fixture is available for deterministic contract testing.`);
   }
   const generator = fixtureGeneration
     ? fixtureGenerator(fixtureGeneration)
@@ -55,21 +102,38 @@ export async function executeDeliveryPathSearch(options, io = console) {
   if (options.generateCandidates && !generator) {
     throw new Error(`${options.surface} has no executable candidate generator; Codex and Claude are tool-enforced reference transports.`);
   }
-  const result = await runDeliveryPathSearch(input, evaluator, { candidates: fixture?.candidates, generator });
-  if (options.persist) result.persistence = persistSearchResult(options.dir, result);
+  let result;
+  try {
+    result = await (dependencies.runDeliveryPathSearch ?? runDeliveryPathSearch)(input, evaluator, { candidates: fixture?.candidates, generator });
+    if (!fixture && options.surface === "opencode" && result.budgets?.evaluations === 0) {
+      result.enforcement = enforcementForSurface("opencode");
+    }
+  } catch (error) {
+    if (!error?.fatalEvaluator || options.surface !== "opencode") throw error;
+    result = unavailableOpenCodeResult({ options, preflight, input, error });
+  }
+  if (options.persist && ["recommendation", "no_safe_recommendation"].includes(result.status)) {
+    result.persistence = (dependencies.persistSearchResult ?? persistSearchResult)(options.dir, result);
+  }
+  printDeliveryPathSearchResult(result, options, io);
+  return result;
+}
+
+function printDeliveryPathSearchResult(result, options, io) {
   if (options.json) {
     io.log(JSON.stringify(result, null, 2));
-    return result;
+    return;
   }
   io.log(`AGDF Delivery Path Search: ${result.status}`);
-  io.log(`Current gate: ${result.current_gate}`);
+  io.log(`Current gate: ${result.current_gate ?? "unknown"}`);
   io.log(`Enforcement: ${result.enforcement.level}`);
   io.log(`Recommendation: ${result.recommendation?.action ?? "none"}`);
-  io.log(`Evaluations: ${result.budgets.evaluations}`);
-  io.log(`Generation: ${result.generation.status} (${result.generation.accepted}/${result.generation.returned} accepted)`);
-  io.log(`Generation budget: ${result.generation.cost_units} cost units, ${result.generation.duration_ms} ms`);
-  if (result.generation.failure_code) io.log(`Generation failure: ${result.generation.failure_code}`);
+  if (result.budgets) io.log(`Evaluations: ${result.budgets.evaluations}`);
+  if (result.generation) {
+    io.log(`Generation: ${result.generation.status} (${result.generation.accepted}/${result.generation.returned} accepted)`);
+    io.log(`Generation budget: ${result.generation.cost_units} cost units, ${result.generation.duration_ms} ms`);
+    if (result.generation.failure_code) io.log(`Generation failure: ${result.generation.failure_code}`);
+  }
   io.log(`Stopping reason: ${result.stopping_reason}`);
   io.log(result.next_gate_action);
-  return result;
 }

package/lib/control-evaluation/gate-policy.js

@@ -29,8 +29,9 @@ export function isGateSatisfied(runState, gate) {
   return isDurableGateArtefactSatisfied(runState, gate);
 }
 
-function qaRevisionRequired(runState) {
-  return gateArtefactStatus(runState, "QA").status === "revise";
+function qaNonPassDecision(runState) {
+  const status = gateArtefactStatus(runState, "QA").status;
+  return status === "revise" || status === "block" ? status : null;
 }
 
 export function transitionDecisionForRunState(runState, verifiedChange = null) {
@@ -233,15 +234,21 @@ export function transitionDecisionForRunState(runState, verifiedChange = null) {
     };
   }
 
-  if (qaRevisionRequired(runState)) {
+  const qaNonPass = qaNonPassDecision(runState);
+  if (qaNonPass) {
+    const blocked = qaNonPass === "block";
     return {
-      status: "open",
+      status: blocked ? "blocked" : "open",
       current_gate: "QA",
-      blocking_reason: "qa_revise_required",
+      blocking_reason: blocked ? "qa_blocked" : "qa_revise_required",
       missing_approval: "none",
-      allowed: ["revise the implementation against the QA findings", "refresh CD+Tests and mandatory reviews", "rerun QA with refreshed evidence"],
+      allowed: blocked
+        ? ["route the blocking QA findings to their authoritative owner", "record the next permitted remediation or upstream decision", "rerun QA only after the blocker is resolved"]
+        : ["revise the implementation against the QA findings", "refresh CD+Tests and mandatory reviews", "rerun QA with refreshed evidence"],
       forbidden: ["request QA approval", "request UAT approval", "release", "claim delivery readiness"],
-      next_allowed_action: "Resolve the QA revise findings, refresh CD+Tests and reviews, then rerun QA. Do not request Approval: QA from a revise report.",
+      next_allowed_action: blocked
+        ? "Resolve or route the blocking QA findings through their authoritative owner, then rerun the required delivery steps. Do not request Approval: QA from a block report."
+        : "Resolve the QA revise findings, refresh CD+Tests and reviews, then rerun QA. Do not request Approval: QA from a revise report.",
     };
   }
 

package/lib/control-evaluation/shared.js

@@ -56,6 +56,7 @@ const backlogStatusLabels = new Map([
   ["blocked", "blocked"],
   ["awaiting qa", "awaiting_qa"],
   ["awaiting uat", "awaiting_uat"],
+  ["awaiting or", "awaiting_or"],
   ["completed", "completed"],
   ["superseded", "superseded"],
   ["abandoned", "abandoned"],

package/lib/delivery-path-search/evaluators/claude.js

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
 import { evaluatorOutputSchema, validateEvaluation } from "../contracts.js";
 import { guardedExecFileSync } from "../transports/read-only-guard.js";
+import { buildEvaluatorPrompt } from "./prompt.js";
 
 export function claudeEvaluator(options = {}) {
   const claudeBin = options.claudeBin ?? "claude";
@@ -13,17 +14,7 @@ export function claudeEvaluator(options = {}) {
     name: "claude",
     metadata: { name: "claude", runtime, model: options.model ?? "configured-default" },
     async evaluate(input, candidate) {
-      const prompt = [
-        "You are an evaluation-only component. Do not use tools, execute commands, or modify files.",
-        `Return JSON matching contract version ${input.contract_version}.`,
-        `Objective: ${input.objective}`,
-        `Current gate: ${input.current_gate}`,
-        `Candidate id: ${candidate.id}`,
-        `Candidate action: ${candidate.action}`,
-        "Score scope_fit, gate_readiness, risk_reduction, evidence_gain, testability, reversibility and cost from 0 to 5.",
-        "Cost 0 is low and 5 is high. uncertainty is 0 low to 5 high.",
-        "Keep rationale concise. child_actions must only contain actions permitted by the current gate.",
-      ].join("\n");
+      const prompt = buildEvaluatorPrompt(input, candidate);
       const args = [
         "-p", "--disallowedTools", "Edit,Write,Bash",
         "--output-format", "json", "--json-schema", JSON.stringify(evaluatorOutputSchema()),

package/lib/delivery-path-search/evaluators/codex.js

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { evaluatorOutputSchema, validateEvaluation } from "../contracts.js";
 import { guardedExecFileSync } from "../transports/read-only-guard.js";
+import { buildEvaluatorPrompt } from "./prompt.js";
 
 export function codexEvaluator(options = {}) {
   const codexBin = options.codexBin ?? "codex";
@@ -21,17 +22,7 @@ export function codexEvaluator(options = {}) {
       const outputPath = join(temp, "output.json");
       try {
         writeFileSync(schemaPath, `${JSON.stringify(evaluatorOutputSchema(), null, 2)}\n`, "utf8");
-        const prompt = [
-          "You are an evaluation-only component. Do not use tools, execute commands, or modify files.",
-          `Return JSON matching contract version ${input.contract_version}.`,
-          `Objective: ${input.objective}`,
-          `Current gate: ${input.current_gate}`,
-          `Candidate id: ${candidate.id}`,
-          `Candidate action: ${candidate.action}`,
-          "Score scope_fit, gate_readiness, risk_reduction, evidence_gain, testability, reversibility and cost from 0 to 5.",
-          "Cost 0 is low and 5 is high. uncertainty is 0 low to 5 high.",
-          "Keep rationale concise. child_actions must only contain actions permitted by the current gate.",
-        ].join("\n");
+        const prompt = buildEvaluatorPrompt(input, candidate);
         const args = [
           "exec", "--sandbox", "read-only", "--ephemeral", "--ignore-user-config",
           "--output-schema", schemaPath, "--output-last-message", outputPath, "--color", "never",

package/lib/delivery-path-search/evaluators/opencode.js

@@ -0,0 +1,234 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import process from "node:process";
+import { validateEvaluation } from "../contracts.js";
+import { guardedExecFileSync } from "../transports/read-only-guard.js";
+import { buildEvaluatorPrompt } from "./prompt.js";
+
+export const OPENCODE_EVALUATOR_AGENT = "agdf-evaluator";
+
+export const OPENCODE_DENY_PERMISSIONS = Object.freeze({
+  "*": "deny",
+  read: "deny",
+  edit: "deny",
+  bash: "deny",
+  task: "deny",
+  webfetch: "deny",
+  websearch: "deny",
+  skill: "deny",
+  lsp: "deny",
+  todowrite: "deny",
+  question: "deny",
+  external_directory: "deny",
+});
+
+const executablePermissions = Object.freeze([
+  "edit", "bash", "task", "webfetch", "websearch", "skill", "lsp", "todowrite", "question",
+]);
+
+export function openCodePermissionEnvironment(env = process.env) {
+  return {
+    ...env,
+    OPENCODE_PERMISSION: JSON.stringify(OPENCODE_DENY_PERMISSIONS),
+  };
+}
+
+function preflightFailure(code, detail, evidence = []) {
+  return {
+    surface: "opencode",
+    status: "failed",
+    code,
+    detail,
+    evidence,
+  };
+}
+
+function extractAgentPermissions(output, agentName) {
+  const marker = `${agentName} (`;
+  const lines = output.split(/\r?\n/);
+  const start = lines.findIndex((line) => line.startsWith(marker));
+  if (start < 0) return null;
+  const mode = lines[start].slice(marker.length).split(")")[0];
+  let jsonStart = -1;
+  let depth = 0;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    const line = lines[index].trim();
+    if (jsonStart < 0 && line === "[") {
+      jsonStart = index;
+      depth = 1;
+      continue;
+    }
+    if (jsonStart >= 0) {
+      for (const character of line) {
+        if (character === "[") depth += 1;
+        if (character === "]") depth -= 1;
+      }
+      if (depth === 0) return { mode, permissions: JSON.parse(lines.slice(jsonStart, index + 1).join("\n")) };
+    }
+  }
+  return null;
+}
+
+function terminalPermissionDecision(permissions, permissionName) {
+  let decision = null;
+  for (const entry of permissions) {
+    if (entry?.pattern === "*" && (entry.permission === "*" || entry.permission === permissionName)) {
+      decision = entry.action;
+    }
+  }
+  return decision;
+}
+
+export function preflightOpenCodeEvaluator(options = {}) {
+  const executable = options.openCodeBin ?? process.env.AGDF_OPENCODE_BIN ?? "opencode";
+  const run = options.execFileSync ?? execFileSync;
+  const cwd = options.cwd ?? process.cwd();
+  const agentName = options.agentName ?? OPENCODE_EVALUATOR_AGENT;
+  const env = openCodePermissionEnvironment(options.env ?? process.env);
+  let runtime;
+  let help;
+  let agents;
+  try {
+    runtime = run(executable, ["--version"], {
+      cwd, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 5000,
+    }).trim();
+  } catch (error) {
+    return preflightFailure("opencode_host_unavailable", (error.stderr || error.message).toString().trim());
+  }
+  try {
+    if (options.execFileSync) {
+      help = run(executable, ["run", "--help"], {
+        cwd, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 5000,
+      });
+    } else {
+      const helpProbe = (options.spawnSync ?? spawnSync)(executable, ["run", "--help"], {
+        cwd, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 5000,
+      });
+      if (helpProbe.error || helpProbe.status !== 0) throw helpProbe.error ?? new Error(helpProbe.stderr || "OpenCode run help failed.");
+      help = `${helpProbe.stdout ?? ""}\n${helpProbe.stderr ?? ""}`;
+    }
+  } catch (error) {
+    return preflightFailure("opencode_run_unavailable", (error.stderr || error.message).toString().trim(), [`opencode ${runtime}`]);
+  }
+  const requiredFlags = ["--pure", "--agent", "--format", "--dir"];
+  const missingFlags = requiredFlags.filter((flag) => !help.includes(flag));
+  if (missingFlags.length) {
+    return preflightFailure("opencode_run_capability_missing", `Missing required flags: ${missingFlags.join(", ")}`, [`opencode ${runtime}`]);
+  }
+  try {
+    agents = run(executable, ["agent", "list", "--pure"], {
+      cwd, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 10000,
+    });
+  } catch (error) {
+    return preflightFailure("opencode_agent_probe_failed", (error.stderr || error.message).toString().trim(), [`opencode ${runtime}`]);
+  }
+  let projection;
+  try {
+    projection = extractAgentPermissions(agents, agentName);
+  } catch (error) {
+    return preflightFailure("opencode_agent_permissions_unparseable", error.message, [`opencode ${runtime}`]);
+  }
+  if (!projection) {
+    return preflightFailure("opencode_evaluator_agent_missing", `OpenCode agent ${agentName} is not available.`, [`opencode ${runtime}`]);
+  }
+  if (projection.mode !== "primary") {
+    return preflightFailure("opencode_evaluator_agent_incompatible", `OpenCode agent ${agentName} must be primary for opencode run --agent; observed ${projection.mode || "unknown"}.`, [
+      `opencode ${runtime}`,
+      `agent:${agentName}`,
+    ]);
+  }
+  const unsafe = executablePermissions.filter((permission) => terminalPermissionDecision(projection.permissions, permission) !== "deny");
+  if (unsafe.length) {
+    return preflightFailure("opencode_evaluator_permissions_unsafe", `Terminal deny is not effective for: ${unsafe.join(", ")}`, [
+      `opencode ${runtime}`,
+      `agent:${agentName}`,
+    ]);
+  }
+  return {
+    surface: "opencode",
+    status: "passed",
+    code: "opencode_evaluator_ready",
+    invocation_id: `${process.pid}-${Date.now()}`,
+    runtime,
+    agent: agentName,
+    evidence: [
+      `opencode ${runtime}`,
+      "opencode run --pure --agent agdf-evaluator --format json",
+      "effective executable permissions terminal-deny",
+    ],
+    env,
+  };
+}
+
+export function parseOpenCodeEvaluatorOutput(raw) {
+  const text = [];
+  for (const line of raw.split(/\r?\n/).filter(Boolean)) {
+    const event = JSON.parse(line);
+    if (event?.type === "error") {
+      const status = event.error?.data?.statusCode;
+      const detail = event.error?.data?.message || event.error?.message || "unknown OpenCode evaluator error";
+      const error = new Error(`OpenCode evaluator error${status ? ` (${status})` : ""}: ${detail}`);
+      error.code = status === 401 || /auth|credential|provider available/i.test(detail)
+        ? "OPENCODE_EVALUATOR_AUTHENTICATION_FAILED"
+        : "OPENCODE_EVALUATOR_UNAVAILABLE";
+      throw error;
+    }
+    if (event?.part?.type === "text" && typeof event.part.text === "string") text.push(event.part.text);
+    else if (event?.type === "text" && typeof event.text === "string") text.push(event.text);
+  }
+  if (!text.length) throw new Error("OpenCode evaluator returned no text event.");
+  if (text.length !== 1) throw new Error(`OpenCode evaluator returned ${text.length} text events; exactly one final payload is required.`);
+  return JSON.parse(text[0]);
+}
+
+function fatalEvaluatorError(error) {
+  const wrapped = new Error(error.message);
+  wrapped.code = typeof error.code === "string" && error.code.startsWith("OPENCODE_EVALUATOR_")
+    ? error.code
+    : error.code === "GENERATOR_MUTATION_DETECTED"
+    ? "OPENCODE_EVALUATOR_MUTATION_DETECTED"
+    : error.code === "GENERATOR_TIMEOUT"
+      ? "OPENCODE_EVALUATOR_TIMEOUT"
+      : error.code === "ENOENT"
+        ? "OPENCODE_EVALUATOR_UNAVAILABLE"
+        : /auth|unauthorized|credential/i.test(`${error.message}\n${error.stderr ?? ""}`)
+          ? "OPENCODE_EVALUATOR_AUTHENTICATION_FAILED"
+          : "OPENCODE_EVALUATOR_OUTPUT_INVALID";
+  wrapped.fatalEvaluator = true;
+  return wrapped;
+}
+
+export function openCodeEvaluator(options = {}) {
+  if (options.preflight?.status !== "passed" || options.preflight.surface !== "opencode") {
+    throw new Error("OpenCode evaluator requires a successful current-invocation preflight.");
+  }
+  const executable = options.openCodeBin ?? process.env.AGDF_OPENCODE_BIN ?? "opencode";
+  const agentName = options.preflight.agent ?? OPENCODE_EVALUATOR_AGENT;
+  return {
+    name: "opencode",
+    metadata: {
+      name: "opencode",
+      runtime: options.preflight.runtime,
+      agent: agentName,
+      preflight: options.preflight.code,
+    },
+    async evaluate(input, candidate) {
+      const args = [
+        "run", "--pure", "--agent", agentName, "--format", "json", "--dir", options.cwd,
+      ];
+      if (options.model) args.push("--model", options.model);
+      args.push(buildEvaluatorPrompt(input, candidate));
+      try {
+        const raw = guardedExecFileSync(executable, args, {
+          cwd: options.cwd,
+          env: options.preflight.env,
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "pipe"],
+          timeout: options.timeoutMs ?? 120000,
+        });
+        return validateEvaluation(parseOpenCodeEvaluatorOutput(raw), candidate.id);
+      } catch (error) {
+        throw fatalEvaluatorError(error);
+      }
+    },
+  };
+}

package/lib/delivery-path-search/evaluators/prompt.js

@@ -0,0 +1,13 @@
+export function buildEvaluatorPrompt(input, candidate) {
+  return [
+    "You are an evaluation-only component. Do not use tools, execute commands, inspect files, delegate work or modify state.",
+    `Return only one JSON object matching contract version ${input.contract_version}.`,
+    `Objective: ${input.objective}`,
+    `Current gate: ${input.current_gate}`,
+    `Candidate id: ${candidate.id}`,
+    `Candidate action: ${candidate.action}`,
+    "Score scope_fit, gate_readiness, risk_reduction, evidence_gain, testability, reversibility and cost from 0 to 5.",
+    "Cost 0 is low and 5 is high. uncertainty is 0 low to 5 high.",
+    "Keep rationale concise. child_actions must only contain actions permitted by the current gate.",
+  ].join("\n");
+}

package/lib/delivery-path-search/search-engine.js

@@ -114,6 +114,7 @@ export async function runDeliveryPathSearch(inputValue, evaluator, options = {})
         }
       }
     } catch (error) {
+      if (error?.fatalEvaluator === true) throw error;
       rejected.push({ candidate_id: candidate.id, action: candidate.action, reason: `invalid_evaluation: ${error.message}` });
     }
   }