create-agdf 0.13.7 → 0.13.8

package/lib/installers/opencode.js

@@ -6,6 +6,7 @@ import process from "node:process";
 import { generatedRoot, pluginDefinition } from "../cli/runtime-context.js";
 import { evaluateOpenCodeRepositoryActivation } from "./opencode-activation.js";
 import { resolveLocalValidator } from "../runtime/local-validator.js";
+import { digestDirectory } from "../runtime/plugin-provenance.js";
 import { validateLocalOpenCodePackageSource } from "./local-development.js";
 
 const contractModules = ["gate-transition.md", "interaction.md", "modes.md", "quality.md", "context-graph.md", "control-scaffold.md", "closeout.md"];
@@ -17,6 +18,7 @@ const globalOpenCodeRuntimeContractOwnershipMarker = "<!-- AGDF-GLOBAL-RUNTIME-C
 const globalOpenCodeValidatorOwnershipMarker = "// AGDF-GLOBAL-LOCAL-VALIDATOR";
 const globalOpenCodeAgentOwnershipMarker = `<!-- AGDF-GLOBAL-AGENT: ${pluginDefinition.opencode.evaluatorAgentName} -->`;
 const globalOpenCodeValidatorPackageOwner = "create-agdf";
+export const openCodePluginEntrypoint = `./node_modules/${pluginDefinition.opencode.npmPackage}/opencode-plugin.js`;
 const testNpmCliPath = process.env.NODE_ENV === "test" ? process.env.AGDF_TEST_NPM_CLI_PATH || "" : "";
 const npmCommand = testNpmCliPath ? process.execPath : process.platform === "win32" ? process.execPath : "npm";
 const npmPrefixArgs = testNpmCliPath ? [testNpmCliPath] : process.platform === "win32" ? [join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js")] : [];
@@ -67,10 +69,14 @@ export function installOpenCodeGlobalPlugin(configDir, dependencies = {}) {
     throw openCodeLifecycleError("configuration", `Refusing to update OpenCode config with non-array plugin field: ${configPath}`, { configPath });
   }
 
-  const plugins = [...(config.plugin ?? [])];
-  const alreadyInstalled = plugins.includes(pluginDefinition.opencode.npmPackage);
+  const plugins = (config.plugin ?? []).map((entry) => (
+    entry === pluginDefinition.opencode.npmPackage || entry.startsWith(`${pluginDefinition.opencode.npmPackage}@`)
+      ? openCodePluginEntrypoint
+      : entry
+  ));
+  const alreadyInstalled = plugins.includes(openCodePluginEntrypoint);
   if (!alreadyInstalled) {
-    plugins.push(pluginDefinition.opencode.npmPackage);
+    plugins.push(openCodePluginEntrypoint);
   }
 
   const nextConfig = {
@@ -128,6 +134,10 @@ export function installOpenCodeGlobalPlugin(configDir, dependencies = {}) {
     throw openCodeLifecycleError("configuration", `Failed to write OpenCode config ${configPath}: ${error.message}`, { configPath });
   }
   const installedPackage = resolveOpenCodePackage(configDir);
+  if (!installedPackage.loadable || !installedPackage.package_root) {
+    throw openCodeLifecycleError("verification", "Installed OpenCode AGDF package is not loadable after installation.", { configDir });
+  }
+  const installedPackageDigest = digestDirectory(installedPackage.package_root);
   const sdkAlignment = alignOpenCodePluginSdk(configDir);
 
   return {
@@ -135,6 +145,7 @@ export function installOpenCodeGlobalPlugin(configDir, dependencies = {}) {
     added: !alreadyInstalled,
     transition: openCodePackageTransition(previousPackage, installedPackage),
     sdk_alignment: sdkAlignment,
+    installed_package: { root: installedPackage.package_root, digest: installedPackageDigest },
     package_source: localPackageSource
       ? { kind: "local_checkout", path: localPackageSource.tarball, digest: localPackageSource.digest, version: localPackageSource.version }
       : { kind: "registry", path: "", digest: "", version: pluginDefinition.version },
@@ -736,7 +747,8 @@ export function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeCon
   const configPath = join(configDir, "opencode.json");
   const configState = readOpenCodeConfig(configPath);
   const plugins = Array.isArray(configState.config.plugin) ? configState.config.plugin : [];
-  const globalConfigured = plugins.includes(pluginDefinition.opencode.npmPackage);
+  const globalConfigured = plugins.includes(openCodePluginEntrypoint);
+  const legacyPluginConfigured = plugins.some((entry) => entry === pluginDefinition.opencode.npmPackage || entry.startsWith(`${pluginDefinition.opencode.npmPackage}@`));
   const packageState = resolveOpenCodePackage(configDir);
   const packageVersionStatus = openCodePackageVersionStatus(packageState);
   const globalNativeSurface = evaluateGlobalOpenCodeSurface(configDir);
@@ -754,7 +766,9 @@ export function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeCon
   const findings = [];
   if (!configState.exists) findings.push("OpenCode global config not found.");
   if (configState.parseError) findings.push(`OpenCode global config is not valid JSON: ${configState.parseError}`);
-  if (!globalConfigured) findings.push(`OpenCode global config does not include ${pluginDefinition.opencode.npmPackage}.`);
+  if (!globalConfigured) findings.push(legacyPluginConfigured
+    ? `OpenCode global config still uses the host-managed npm cache entry for ${pluginDefinition.opencode.npmPackage}; rerun installation to bind the verified local package entrypoint.`
+    : `OpenCode global config does not include ${openCodePluginEntrypoint}.`);
   if (!packageState.loadable) findings.push(`${pluginDefinition.opencode.npmPackage} is not loadable from the OpenCode config directory.`);
   if (packageVersionStatus === "outdated") findings.push(`${pluginDefinition.opencode.npmPackage} version ${packageState.installed_version} is outdated; expected ${pluginDefinition.version}.`);
   if (packageVersionStatus === "unknown" && packageState.loadable) findings.push(`${pluginDefinition.opencode.npmPackage} is loadable but its installed version is unknown.`);
@@ -783,6 +797,8 @@ export function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeCon
       exists: configState.exists,
       parse_error: configState.parseError,
       plugin_configured: globalConfigured,
+      plugin_entrypoint: openCodePluginEntrypoint,
+      legacy_plugin_configured: legacyPluginConfigured,
     },
     package: {
       name: pluginDefinition.opencode.npmPackage,

package/lib/installers/plugin-installers.js

@@ -30,6 +30,10 @@ export function installCodexGlobalPlugin({ exec = execFileSync, prepare = prepar
         ...(transaction.existingClassification === "owned_pre_provenance_rebuild" ? ["marketplace_recovery:owned_pre_provenance_rebuild", "loaded_session:restart_required"] : []),
         ...(expectedInstallVersion === expectedVersion ? [] : [`canonical_version:${expectedVersion}`, `local_install_version:${expectedInstallVersion}`]),
       ],
+      pluginRoot: transaction.pluginRoot ?? null,
+      digest: transaction.digest ?? null,
+      runtimeDigest: transaction.runtimeDigest ?? null,
+      sourceDigest: transaction.sourceDigest ?? null,
       nativeOutput: nativeOutput.filter(Boolean).map(String),
     };
   } catch (error) {
@@ -77,6 +81,10 @@ export function installClaudeGlobalPlugin({ exec = execFileSync, prepare = prepa
         ...(transaction.existingClassification === "owned_pre_provenance_rebuild" ? ["marketplace_recovery:owned_pre_provenance_rebuild", "loaded_session:restart_required"] : []),
         ...(installedVersion ? [] : ["host_did_not_expose_version"]),
       ],
+      pluginRoot: transaction.pluginRoot ?? null,
+      digest: transaction.digest ?? null,
+      runtimeDigest: transaction.runtimeDigest ?? null,
+      sourceDigest: transaction.sourceDigest ?? null,
       nativeOutput: nativeOutput.filter(Boolean).map(String),
     };
   } catch (error) {

package/lib/lifecycle/presentation.js

@@ -9,6 +9,9 @@ const surfaceLabels = Object.freeze({
 function titleFor(report) {
   if (report.result === "failed") return "AGDF installation failed";
   if (report.result === "partial") return "AGDF installation partially completed";
+  if (report.result === "preview") return report.operation === "uninstall"
+    ? "AGDF uninstall preview"
+    : "AGDF installation cancelled";
   if (report.operation === "repository_setup") return "AGDF repository setup complete";
   return "AGDF installation complete";
 }
@@ -28,18 +31,55 @@ export function lifecycleCardLines(report) {
     `Installation: ${report.installation.status}`,
     `Activation: ${report.activation.status}`,
     `Repository delivery: ${report.delivery.status}`,
+    `Automatic runtime checks: requested=${report.runtime_checks.requested}; effective=${report.runtime_checks.effective}; reason=${report.runtime_checks.reason}`,
     `Verification: ${report.verification.status}`,
     `Restart required: ${report.restart.required ? "yes" : "no"}${report.restart.reason !== "none" ? ` (${report.restart.reason})` : ""}`,
     `Next action: ${report.next_action.text}`,
   ];
 }
 
-export function printLifecycleResult(report, { json = false, io = console } = {}) {
+function friendlyRuntimeCheckState(report) {
+  if (report.runtime_checks.requested === "cancelled") return "Cancelled";
+  if (report.runtime_checks.effective === "enabled") return "On";
+  if (report.runtime_checks.effective === "manual") return "Manual";
+  if (report.runtime_checks.effective === "decision_required") return `Waiting for ${surfaceLabels[report.surface]} permission`;
+  if (report.runtime_checks.effective === "renewal_required") return "Needs your review";
+  if (["degraded", "failed", "unavailable"].includes(report.runtime_checks.effective)) return "Not available; use manual checks";
+  return report.runtime_checks.requested === "enabled" ? "Requested; verification pending" : "Not configured";
+}
+
+function compactVersionLine(report) {
+  if (report.version.transition === "updated" && report.version.previous && report.version.installed) {
+    return `Updated: ${report.version.previous} -> ${report.version.installed} (${report.version.status})`;
+  }
+  if (report.version.installed) return `Version: ${report.version.installed} (${report.version.status})`;
+  if (report.version.expected) return `Version: not verified (expected ${report.version.expected})`;
+  return "Version: not verified";
+}
+
+export function compactLifecycleCardLines(report) {
+  if (report.result === "preview") return [
+    titleFor(report),
+    "No changes were made.",
+    `Next: ${report.next_action.text}`,
+  ];
+  return [
+    report.result === "success"
+      ? `AGDF ${report.operation === "update" ? "updated" : "installed"} for ${surfaceLabels[report.surface]}`
+      : titleFor(report),
+    compactVersionLine(report),
+    `Installation: ${report.installation.status === "healthy" ? "Ready" : report.installation.status}`,
+    `Automatic checks: ${friendlyRuntimeCheckState(report)}`,
+    `Next: ${report.next_action.text}`,
+  ];
+}
+
+export function printLifecycleResult(report, { json = false, compact = false, io = console } = {}) {
   if (json) {
     io.log(JSON.stringify(report, null, 2));
     return;
   }
-  for (const line of lifecycleCardLines(report)) io.log(line);
+  for (const line of compact ? compactLifecycleCardLines(report) : lifecycleCardLines(report)) io.log(line);
   if (report.failure) io.log(`Failure phase: ${report.failure.phase}: ${report.failure.message}`);
   if (report.retained.length) {
     io.log("Retained:");
@@ -56,5 +96,6 @@ export function printGeneralStatus(report, { json = false, io = console } = {})
   io.log(`Installation: ${report.installation.status}${report.installation.version ? ` (${report.installation.version})` : ""}`);
   io.log(`Repository: ${report.repository.status}`);
   io.log(`Delivery: ${report.delivery.status}${report.delivery.current_gate ? ` (${report.delivery.current_gate})` : ""}`);
+  io.log(`Automatic runtime checks: requested=${report.runtime_checks.requested}; effective=${report.runtime_checks.effective}; reason=${report.runtime_checks.reason}`);
   io.log(`Next action: ${report.next_action.text}`);
 }

package/lib/lifecycle/result.js

@@ -39,6 +39,15 @@ export function createLifecycleResult(input = {}) {
     delivery: {
       status: text(input.delivery?.status) || "not_evaluated",
     },
+    runtime_checks: {
+      requested: text(input.runtime_checks?.requested) || "unknown",
+      effective: text(input.runtime_checks?.effective) || "unknown",
+      reason: text(input.runtime_checks?.reason) || "not_evaluated",
+      capability_identity: text(input.runtime_checks?.capability_identity) || null,
+      verification: text(input.runtime_checks?.verification) || "not_evaluated",
+      mutation: text(input.runtime_checks?.mutation) || "none",
+      rollback: text(input.runtime_checks?.rollback) || "none",
+    },
     restart: {
       required: Boolean(input.restart?.required),
       reason: text(input.restart?.reason) || "none",

package/lib/lifecycle/status.js

@@ -6,6 +6,7 @@ import { evaluateGateCheck } from "../control-evaluation/gate-check.js";
 import { evaluateOpenCodeStatus } from "../installers/opencode.js";
 import { inspectPluginSurface } from "../installers/plugin-installers.js";
 import { inspectGeneratedRepositoryMarketplace } from "../runtime/plugin-provenance.js";
+import { runtimeCheckStatus } from "../runtime-check-consent/service.js";
 
 function deliveryStatus(targetDir, selection, dependencies) {
   const controlDir = join(targetDir, ".agdf", "control");
@@ -95,6 +96,9 @@ export function evaluateGeneralStatus(targetDir, options = {}, dependencies = {}
   }
   const repository = repositoryStatus(targetDir, surface);
   const delivery = deliveryStatus(targetDir, { runId: options.runId }, deps);
+  const runtimeChecks = ["codex", "claude", "opencode"].includes(surface)
+    ? runtimeCheckStatus(options.dataRoot, surface)
+    : { requested: "unknown", effective: "unavailable", reason: "unsupported_host_capability" };
   const nextText = surface === "multiple"
     ? "Multiple AGDF host surfaces were detected; rerun status with an explicit --surface."
     : surface === "generic"
@@ -112,5 +116,5 @@ export function evaluateGeneralStatus(targetDir, options = {}, dependencies = {}
     : delivery.status === "not_configured"
     ? "Start a new task; status created no run and requires no approval. Initialize durable control only when the repository needs it."
     : "Continue with the reported delivery next step.";
-  return { schema_version: 1, installation, repository, delivery, next_action: { kind: "action", text: nextText } };
+  return { schema_version: 1, installation, repository, delivery, runtime_checks: runtimeChecks, next_action: { kind: "action", text: nextText } };
 }

package/lib/runtime-check-consent/adapters.js

@@ -0,0 +1,42 @@
+function fixedCommand(command) {
+  if (typeof command !== "string" || !command.trim() || /[\n\r;&|*?]/.test(command)) {
+    throw new Error("AGDF_RUNTIME_CHECK_COMMAND_NOT_EXACT");
+  }
+  return command.trim();
+}
+
+export function codexRuntimeCheckEvidence({ capabilityIdentity, observedIdentity, hookEnabled, reviewRequired = false }) {
+  if (hookEnabled && observedIdentity === capabilityIdentity) return { status: "enabled", capability_identity: capabilityIdentity, reason: "none" };
+  if (observedIdentity && observedIdentity !== capabilityIdentity) return { status: "renewal_required", reason: "capability_identity_changed" };
+  return { status: "decision_required", reason: reviewRequired ? "host_review_required" : "host_permission_unverified" };
+}
+
+export function claudePermissionRule({ platform, command }) {
+  const exact = fixedCommand(command);
+  return platform === "win32" ? `PowerShell(${exact})` : `Bash(${exact})`;
+}
+
+export function applyClaudeExactRule(settings, { rule, deny = [], ask = [] }) {
+  if (!settings || typeof settings !== "object" || Array.isArray(settings)) throw new Error("AGDF_CLAUDE_SETTINGS_INVALID");
+  if ([...deny, ...ask].includes(rule)) return { status: "degraded", reason: "host_permission_conflict", settings };
+  const next = structuredClone(settings);
+  next.permissions ??= {};
+  if (Array.isArray(next.permissions.allow) && next.permissions.allow.some((entry) => entry.includes("*") || entry !== entry.trim())) {
+    throw new Error("AGDF_CLAUDE_BROAD_OR_MALFORMED_RULE");
+  }
+  next.permissions.allow = [...new Set([...(next.permissions.allow ?? []), rule])];
+  return { status: "configured", reason: "none", settings: next };
+}
+
+export function revokeClaudeExactRule(settings, rule) {
+  const next = structuredClone(settings);
+  if (Array.isArray(next.permissions?.allow)) next.permissions.allow = next.permissions.allow.filter((entry) => entry !== rule);
+  return next;
+}
+
+export function openCodeRuntimeCheckEvidence({ capabilityIdentity, observedIdentity, packageLoadable, hookObserved }) {
+  if (!packageLoadable) return { status: "unavailable", reason: "unsupported_host_capability" };
+  if (observedIdentity !== capabilityIdentity) return { status: "renewal_required", reason: "installed_identity_mismatch" };
+  if (!hookObserved) return { status: "degraded", reason: "host_permission_unverified" };
+  return { status: "enabled", capability_identity: capabilityIdentity, reason: "none" };
+}

package/lib/runtime-check-consent/claude-settings.js

@@ -0,0 +1,71 @@
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import process from "node:process";
+import { renameSyncWithRetry } from "../fs-swap.js";
+import { applyClaudeExactRule, revokeClaudeExactRule } from "./adapters.js";
+
+export function defaultClaudeSettingsPath({ env = process.env, home = homedir() } = {}) {
+  return join(resolve(env.CLAUDE_CONFIG_DIR || join(home, ".claude")), "settings.json");
+}
+
+export function readClaudeSettings(path = defaultClaudeSettingsPath()) {
+  if (!existsSync(path)) return { exists: false, settings: {} };
+  const stats = lstatSync(path);
+  if (!stats.isFile() || stats.isSymbolicLink()) throw new Error("AGDF_CLAUDE_SETTINGS_UNOWNED_PATH");
+  try {
+    const settings = JSON.parse(readFileSync(path, "utf8"));
+    if (!settings || typeof settings !== "object" || Array.isArray(settings)) throw new Error("not an object");
+    return { exists: true, settings };
+  } catch (error) {
+    throw new Error(`AGDF_CLAUDE_SETTINGS_INVALID: ${error.message}`);
+  }
+}
+
+function atomicSettingsWrite(path, settings) {
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = `${path}.agdf-tmp-${process.pid}`;
+  const backup = `${path}.agdf-backup-${process.pid}`;
+  const hadPrevious = existsSync(path);
+  const mode = hadPrevious ? lstatSync(path).mode & 0o777 : 0o600;
+  writeFileSync(temp, `${JSON.stringify(settings, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode });
+  if (process.platform !== "win32") chmodSync(temp, mode);
+  try {
+    if (hadPrevious && process.platform === "win32") renameSyncWithRetry(path, backup);
+    renameSyncWithRetry(temp, path);
+    if (hadPrevious && process.platform === "win32") rmSync(backup, { force: true });
+  } catch (error) {
+    try { rmSync(temp, { force: true }); } catch {}
+    if (hadPrevious && process.platform === "win32" && existsSync(backup) && !existsSync(path)) renameSyncWithRetry(backup, path);
+    throw error;
+  }
+}
+
+export function configureClaudeExactRuntimeRule({ path = defaultClaudeSettingsPath(), rule }) {
+  const before = readClaudeSettings(path);
+  const permissions = before.settings.permissions ?? {};
+  const applied = applyClaudeExactRule(before.settings, {
+    rule,
+    deny: Array.isArray(permissions.deny) ? permissions.deny : [],
+    ask: Array.isArray(permissions.ask) ? permissions.ask : [],
+  });
+  if (applied.status !== "configured") return { ...applied, path, rollback() {} };
+  atomicSettingsWrite(path, applied.settings);
+  return {
+    status: "configured",
+    reason: "host_permission_unverified",
+    path,
+    rollback() {
+      if (before.exists) atomicSettingsWrite(path, before.settings);
+      else rmSync(path, { force: true });
+    },
+  };
+}
+
+export function revokeClaudeRuntimeRule({ path = defaultClaudeSettingsPath(), rule }) {
+  const before = readClaudeSettings(path);
+  if (!before.exists) return { status: "manual", reason: "configuration_missing", path };
+  const next = revokeClaudeExactRule(before.settings, rule);
+  atomicSettingsWrite(path, next);
+  return { status: "manual", reason: "consent_not_provided", path };
+}

package/lib/runtime-check-consent/contract.js

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+
+const OPERATIONS = Object.freeze([
+  "resolve-local-runtime",
+  "inspect-control-state",
+  "render-bounded-orientation",
+]);
+
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]));
+}
+
+export function validateRuntimeCheckCapability(capability) {
+  if (capability?.schemaVersion !== 1 || capability.capabilityId !== "automatic-runtime-checks") {
+    throw new Error("AGDF_RUNTIME_CHECK_CAPABILITY_INVALID: schema or capability id");
+  }
+  if (!Number.isInteger(capability.adapterContractVersion) || capability.adapterContractVersion < 1) {
+    throw new Error("AGDF_RUNTIME_CHECK_CAPABILITY_INVALID: adapter contract version");
+  }
+  if (capability.entrypoint !== "runtime/agdf-session-check.js") {
+    throw new Error("AGDF_RUNTIME_CHECK_CAPABILITY_INVALID: fixed entrypoint required");
+  }
+  if (JSON.stringify(capability.operations) !== JSON.stringify(OPERATIONS)) {
+    throw new Error("AGDF_RUNTIME_CHECK_CAPABILITY_INVALID: closed operation vocabulary required");
+  }
+  const constraints = capability.constraints ?? {};
+  if (constraints.arguments !== "forbidden" || constraints.filesystemWrites !== "forbidden"
+      || constraints.network !== "forbidden" || constraints.gateAuthority !== "none") {
+    throw new Error("AGDF_RUNTIME_CHECK_CAPABILITY_INVALID: read-only constraints required");
+  }
+  const surfaces = capability.surfaces ?? {};
+  if (surfaces.codex !== "native-hook-review" || surfaces.claude !== "exact-command-rule"
+      || surfaces.opencode !== "plugin-internal"
+      || surfaces["portable-skills"] !== "manual-external-required") {
+    throw new Error("AGDF_RUNTIME_CHECK_CAPABILITY_INVALID: surface contract");
+  }
+  return capability;
+}
+
+export function runtimeCheckCapabilityIdentity({ capability, surface, runtimeDigest, sourceDigest, command }) {
+  validateRuntimeCheckCapability(capability);
+  if (!["codex", "claude", "opencode"].includes(surface)) throw new Error("AGDF_RUNTIME_CHECK_SURFACE_INVALID");
+  for (const [name, value] of Object.entries({ runtimeDigest, sourceDigest })) {
+    if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value)) throw new Error(`AGDF_RUNTIME_CHECK_IDENTITY_INVALID: ${name}`);
+  }
+  if (typeof command !== "string" || !command.trim()) throw new Error("AGDF_RUNTIME_CHECK_IDENTITY_INVALID: command");
+  const payload = stable({
+    schema_version: 1,
+    surface,
+    capability,
+    runtime_digest: runtimeDigest,
+    source_digest: sourceDigest,
+    command: command.trim(),
+  });
+  return createHash("sha256").update(JSON.stringify(payload)).digest("hex");
+}
+
+export function fixedRuntimeCheckCommand(surface, pluginRoot, platform = process.platform) {
+  if (surface === "opencode") return "plugin:agdf:automatic-runtime-checks";
+  if (surface === "codex" || surface === "claude") {
+    return platform === "win32"
+      ? "node \"$([Environment]::GetEnvironmentVariable('PLUGIN_ROOT') + [Environment]::GetEnvironmentVariable('CLAUDE_PLUGIN_ROOT'))\\runtime\\agdf-session-check.js\""
+      : "node \"${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/runtime/agdf-session-check.js\"";
+  }
+  const normalizedRoot = platform === "win32" ? pluginRoot.replaceAll("/", "\\") : pluginRoot;
+  return `node \"${normalizedRoot}${platform === "win32" ? "\\" : "/"}runtime${platform === "win32" ? "\\" : "/"}agdf-session-check.js\"`;
+}
+
+export const runtimeCheckOperations = OPERATIONS;

package/lib/runtime-check-consent/coordinator.js

@@ -0,0 +1,37 @@
+export const RUNTIME_CHECK_DECISIONS = Object.freeze(["enable", "manual", "cancel"]);
+
+export function resolveRuntimeCheckDecision({ explicitValue, interactive = false, ask }) {
+  if (explicitValue !== undefined) {
+    if (!RUNTIME_CHECK_DECISIONS.includes(explicitValue)) throw new Error("AGDF_RUNTIME_CHECK_DECISION_INVALID");
+    return explicitValue;
+  }
+  if (!interactive || typeof ask !== "function") return "manual";
+  const answer = ask({
+    question: "Allow this AGDF installation to run narrow local read-only checks automatically?",
+    options: [...RUNTIME_CHECK_DECISIONS],
+    default: null,
+  });
+  if (!RUNTIME_CHECK_DECISIONS.includes(answer)) return "cancel";
+  return answer;
+}
+
+export function consentDisclosure(surface) {
+  const permissionOwner = surface === "codex" ? "Codex native hook trust"
+    : surface === "claude" ? "Claude Code user permission settings"
+    : "OpenCode plugin and explicit permission configuration";
+  return Object.freeze({
+    surface,
+    installation_scope: "global user installation",
+    runs: "one argument-free local session check",
+    when: "at session start",
+    executable: "runtime/agdf-session-check.js inside the installed AGDF runtime",
+    reads: "AGDF runtime identity and .agdf/control state in the current repository",
+    writes: "one AGDF-owned intent receipt and, only where supported, one exact host permission rule",
+    network: "none",
+    permission_owner: permissionOwner,
+    renewal: "material command, runtime, source, scope or adapter identity change requires renewed consent",
+    revocation: `npx --yes @agdf/cli@latest runtime-checks manual --surface ${surface}`,
+    gate_authority: "none",
+    choices: [...RUNTIME_CHECK_DECISIONS],
+  });
+}

package/lib/runtime-check-consent/service.js

@@ -0,0 +1,181 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import process from "node:process";
+import { generatedRoot, pluginDefinition } from "../cli/runtime-context.js";
+import { defaultOpenCodeConfigDir, resolveOpenCodeInstalledPackage } from "../installers/opencode.js";
+import { defaultAgdfDataRoot } from "../installers/local-marketplace.js";
+import { digestNormalizedPluginSource } from "../runtime/plugin-provenance.js";
+import { fixedRuntimeCheckCommand, runtimeCheckCapabilityIdentity } from "./contract.js";
+import { consentDisclosure, resolveRuntimeCheckDecision } from "./coordinator.js";
+import { claudePermissionRule } from "./adapters.js";
+import { configureClaudeExactRuntimeRule, defaultClaudeSettingsPath, revokeClaudeRuntimeRule } from "./claude-settings.js";
+import { createRuntimeCheckReceipt, readRuntimeCheckReceipt, writeRuntimeCheckReceipt } from "./state.js";
+
+export { fixedRuntimeCheckCommand } from "./contract.js";
+
+export function prepareInstallConsent(surface, options = {}, adapters = {}) {
+  const explicit = options.runtimeChecksDecision;
+  const interactive = explicit === undefined && Boolean(adapters.interactive);
+  const answer = interactive ? adapters.ask?.(consentDisclosure(surface)) : undefined;
+  const decision = resolveRuntimeCheckDecision({ explicitValue: explicit ?? answer, interactive: false });
+  return { decision, persist: explicit !== undefined || interactive, disclosure: consentDisclosure(surface) };
+}
+
+function prospectiveRuntimeCheckIdentity(surface, platform = process.platform) {
+  if (surface === "opencode") {
+    const installed = resolveOpenCodeInstalledPackage(defaultOpenCodeConfigDir(), pluginDefinition.opencode.npmPackage);
+    if (!installed.loadable || !installed.digest) return null;
+    return runtimeCheckCapabilityIdentity({
+      capability: pluginDefinition.automaticRuntimeChecks,
+      surface,
+      runtimeDigest: installed.digest,
+      sourceDigest: installed.digest,
+      command: fixedRuntimeCheckCommand(surface, installed.root, platform),
+    });
+  }
+  if (!["codex", "claude"].includes(surface)) return null;
+  const pluginRoot = join(generatedRoot, "plugins", "agdf");
+  let runtimeManifest;
+  try { runtimeManifest = JSON.parse(readFileSync(join(pluginRoot, "runtime", "runtime-manifest.json"), "utf8")); } catch { return null; }
+  if (!/^[a-f0-9]{64}$/.test(runtimeManifest?.digest ?? "")) return null;
+  const sourceDigest = digestNormalizedPluginSource(pluginRoot, pluginDefinition.version);
+  const command = fixedRuntimeCheckCommand(surface, pluginRoot, platform);
+  return runtimeCheckCapabilityIdentity({
+    capability: pluginDefinition.automaticRuntimeChecks,
+    surface,
+    runtimeDigest: runtimeManifest.digest,
+    sourceDigest,
+    command,
+  });
+}
+
+export function retainCurrentInstallConsent(surface, dataRoot = defaultAgdfDataRoot(), platform = process.platform) {
+  const capabilityIdentity = prospectiveRuntimeCheckIdentity(surface, platform);
+  if (!capabilityIdentity) return null;
+  const current = readRuntimeCheckReceipt(dataRoot, surface);
+  if (current.status !== "valid" || current.receipt.capability_identity !== capabilityIdentity) return null;
+  return {
+    decision: current.receipt.requested_state === "enabled" ? "enable" : "manual",
+    persist: false,
+    retained: true,
+    disclosure: consentDisclosure(surface),
+  };
+}
+
+export function persistInstallConsent({ surface, decision, installed, dataRoot, platform, claudeSettingsPath }) {
+  if (decision === "cancel") return { requested: "cancelled", effective: "cancelled", reason: "consent_not_provided", capability_identity: null, verification: "not_attempted", mutation: "none", rollback: "none" };
+  const runtimeDigest = installed?.runtimeDigest ?? installed?.digest;
+  if (!installed?.pluginRoot || !runtimeDigest || !installed?.sourceDigest) {
+    return { requested: decision === "enable" ? "enabled" : "manual", effective: "manual", reason: "host_permission_unverified", capability_identity: null, verification: "unavailable", mutation: "none", rollback: "none" };
+  }
+  const command = fixedRuntimeCheckCommand(surface, installed.pluginRoot, platform);
+  const capabilityIdentity = runtimeCheckCapabilityIdentity({
+    capability: pluginDefinition.automaticRuntimeChecks,
+    surface,
+    runtimeDigest,
+    sourceDigest: installed.sourceDigest,
+    command,
+  });
+  const receipt = createRuntimeCheckReceipt({ surface, decision, capabilityIdentity, command });
+  let configured = null;
+  let configurationReason = null;
+  if (surface === "claude" && decision === "enable") {
+    configured = configureClaudeExactRuntimeRule({
+      path: claudeSettingsPath ?? defaultClaudeSettingsPath(),
+      rule: claudePermissionRule({ platform: platform ?? process.platform, command }),
+    });
+    if (configured.status !== "configured") {
+      configurationReason = configured.reason;
+      configured = null;
+    }
+  }
+  try {
+    writeRuntimeCheckReceipt(dataRoot ?? defaultAgdfDataRoot(), receipt);
+  } catch (error) {
+    configured?.rollback();
+    throw error;
+  }
+  if (configurationReason) return { requested: "enabled", effective: "degraded", reason: configurationReason, capability_identity: capabilityIdentity, verification: "conflict", mutation: "receipt_written", rollback: "none" };
+  return {
+    requested: receipt.requested_state,
+    effective: receipt.requested_state === "manual" ? "manual" : "decision_required",
+    reason: receipt.requested_state === "manual" ? "consent_not_provided" : "host_permission_unverified",
+    capability_identity: capabilityIdentity,
+    verification: receipt.requested_state === "manual" ? "not_required" : "host_unverified",
+    mutation: surface === "claude" && decision === "enable" ? "exact_rule_and_receipt_written" : "receipt_written",
+    rollback: "none",
+  };
+}
+
+export function setRuntimeChecksManual({ dataRoot = defaultAgdfDataRoot(), surface, platform = process.platform, claudeSettingsPath }) {
+  const result = readRuntimeCheckReceipt(dataRoot, surface);
+  if (result.status === "receipt_missing") return { requested: "manual", effective: "manual", reason: "consent_not_provided", capability_identity: null, verification: "not_required", mutation: "none", rollback: "none", path: result.path };
+  if (result.status !== "valid") return { requested: "manual", effective: result.status, reason: result.status, capability_identity: null, verification: "unavailable", mutation: "none", rollback: "none", path: result.path };
+  if (surface === "claude" && result.receipt.requested_state === "enabled") {
+    revokeClaudeRuntimeRule({
+      path: claudeSettingsPath ?? defaultClaudeSettingsPath(),
+      rule: claudePermissionRule({ platform, command: result.receipt.command }),
+    });
+  }
+  const receipt = createRuntimeCheckReceipt({
+    surface,
+    decision: "manual",
+    capabilityIdentity: result.receipt.capability_identity,
+    command: result.receipt.command,
+  });
+  writeRuntimeCheckReceipt(dataRoot, receipt);
+  return {
+    requested: "manual",
+    effective: "manual",
+    reason: "consent_not_provided",
+    capability_identity: receipt.capability_identity,
+    verification: "not_required",
+    mutation: surface === "claude" ? "exact_owned_rule_removed" : "receipt_updated",
+    rollback: "none",
+    path: result.path,
+  };
+}
+
+export function runtimeCheckStatus(dataRoot = defaultAgdfDataRoot(), surface, platform = process.platform) {
+  const result = readRuntimeCheckReceipt(dataRoot, surface);
+  if (result.status !== "valid") return { requested: "unknown", effective: result.status, reason: result.status, capability_identity: null, verification: "unavailable", mutation: "none", rollback: "none", path: result.path };
+  const currentIdentity = prospectiveRuntimeCheckIdentity(surface, platform);
+  if (currentIdentity && currentIdentity !== result.receipt.capability_identity) {
+    return { requested: result.receipt.requested_state, effective: "renewal_required", reason: "capability_identity_changed", capability_identity: result.receipt.capability_identity, verification: "identity_mismatch", mutation: "none", rollback: "none", path: result.path };
+  }
+  return { requested: result.receipt.requested_state, effective: result.receipt.requested_state === "manual" ? "manual" : "decision_required", reason: result.receipt.requested_state === "manual" ? "consent_not_provided" : "host_permission_unverified", capability_identity: result.receipt.capability_identity, verification: result.receipt.requested_state === "manual" ? "not_required" : "host_unverified", mutation: "none", rollback: "none", path: result.path };
+}
+
+export function executeOpenCodeAutomaticRuntimeCheck({
+  directory = process.cwd(),
+  dataRoot = defaultAgdfDataRoot(),
+  packageRoot = fileURLToPath(new URL("../../", import.meta.url)),
+  run = spawnSync,
+  executable = process.platform === "win32" ? "node.exe" : "node",
+  statusResolver = runtimeCheckStatus,
+  entrypointExists = existsSync,
+} = {}) {
+  const status = statusResolver(dataRoot, "opencode");
+  if (status.requested !== "enabled" || status.effective !== "decision_required") {
+    return { ...status, ran: false, output: "" };
+  }
+  const entrypoint = join(packageRoot, "generated", "plugins", "agdf", "runtime", "agdf-session-check.js");
+  if (!entrypointExists(entrypoint)) {
+    return { ...status, effective: "unavailable", reason: "unsupported_host_capability", verification: "entrypoint_missing", ran: false, output: "" };
+  }
+  const child = run(executable, [entrypoint], {
+    cwd: directory,
+    env: { ...process.env, AGDF_SURFACE: "opencode" },
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 10000,
+    maxBuffer: 1024 * 1024,
+  });
+  const output = String(child.stdout || "").trim().slice(0, 20000);
+  if (child.status !== 0 || !output.includes("AGDF automatic runtime check:")) {
+    return { ...status, effective: "degraded", reason: "host_permission_unverified", verification: "execution_failed", ran: true, output: "" };
+  }
+  return { ...status, effective: "enabled", reason: "none", verification: "host_observed", ran: true, output };
+}