@kylecheng3146/agent-ops 0.1.3 → 0.1.5

package/dist/runtime/src/install/harness.js

@@ -1,8 +1,235 @@
+import { buildClaudeHookSettings, mergeClaudeSettings, stripClaudeManagedHooks } from "../adapters/claude/config.js";
+import { CLAUDE_CAPABILITY_REGISTRATIONS } from "../adapters/claude/events.js";
+import { normalizeClaudeHookInput } from "../adapters/claude/input.js";
+import { claudeHookOutput } from "../adapters/claude/output.js";
+import { claudeSurfaces } from "../adapters/claude/surfaces.js";
+import { buildCodexHookConfig, CODEX_MANAGED_MARKER, mergeCodexHookConfig, stripCodexManagedHooks } from "../adapters/codex/config.js";
+import { CODEX_CAPABILITY_REGISTRATIONS } from "../adapters/codex/events.js";
+import { normalizeCodexHookInput } from "../adapters/codex/input.js";
+import { codexHookOutput } from "../adapters/codex/output.js";
+import { codexSurfaces } from "../adapters/codex/surfaces.js";
+import { buildOpencodePlugin, isOpencodePluginRegistered, opencodePluginTarget } from "../adapters/opencode/config.js";
+import { OPENCODE_CAPABILITY_REGISTRATIONS } from "../adapters/opencode/events.js";
+import { normalizeOpencodeHookInput } from "../adapters/opencode/input.js";
+import { opencodeHookOutput } from "../adapters/opencode/output.js";
+import { opencodeSurfaces } from "../adapters/opencode/surfaces.js";
 import { AgentOpsError } from "../fs/paths.js";
-export const COMMON_AGENTS_BLOCK = "## Loop Engineering\n\nUse `.agent-ops/AGENTS.md` as the canonical Loop Engineering specification for this project.\n";
-export const COMMON_CLAUDE_BLOCK = "## Loop Engineering\n\nUse `.agent-ops/CLAUDE.md` as the canonical Loop Engineering specification for this project.\n";
-function managedRules(id, context) {
-    const instructionFile = id === "codex" ? "AGENTS.md" : "CLAUDE.md";
+import { findSurfaceById, findSurfaceByPath, isWritableSurface } from "./surfaces.js";
+export const HARNESS_IDS = [
+    "codex",
+    "claude",
+    "opencode"
+];
+const CLAUDE_HOOK_MARKER = "--managed-by=agent-ops";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseJsonSource(source) {
+    if (typeof source !== "string") {
+        return source;
+    }
+    if (source.trim().length === 0) {
+        return {};
+    }
+    try {
+        return JSON.parse(source);
+    }
+    catch {
+        return null;
+    }
+}
+function jsonHookRegistered(control, source, capabilities) {
+    if (control.buildHooks === undefined ||
+        control.isManagedHandler === undefined) {
+        return false;
+    }
+    const events = Object.keys(control.buildHooks(capabilities, "probe").hooks);
+    if (events.length === 0) {
+        return true;
+    }
+    const parsed = parseJsonSource(source);
+    if (!isRecord(parsed) || !isRecord(parsed.hooks)) {
+        return false;
+    }
+    const hooks = parsed.hooks;
+    return events.every((event) => {
+        const groups = hooks[event];
+        return (Array.isArray(groups) &&
+            groups.some((group) => isRecord(group) &&
+                Array.isArray(group.hooks) &&
+                group.hooks.some(control.isManagedHandler)));
+    });
+}
+function runtimeFailureResult(capability, registrations) {
+    const runtimeFailure = registrations.find((registration) => registration.capability === capability)?.runtimeFailure;
+    return {
+        action: runtimeFailure === "fail-closed" ? "block" : "continue",
+        status: "UNKNOWN",
+        code: `${capability.replaceAll("-", "_").toUpperCase()}_UNAVAILABLE`
+    };
+}
+function createJsonDescriptor(options) {
+    const control = {
+        instructionFile: options.instructionFile,
+        routing: options.routing,
+        hookPath: options.hookPath,
+        surfaces: options.surfaces,
+        ownSettingsKeys: options.ownSettingsKeys,
+        buildHooks: options.buildHooks,
+        mergeHooks: options.mergeHooks,
+        stripHooks: options.stripHooks,
+        isManagedHandler: options.isManagedHandler,
+        registrations: options.registrations,
+        plan: (context) => planCommonHarnessContribution(options.id, context),
+        hookRegistered: (source, capabilities) => jsonHookRegistered(control, source, capabilities)
+    };
+    return {
+        id: options.id,
+        control,
+        runtime: {
+            normalizeInput: options.normalizeInput,
+            formatOutput: options.formatOutput,
+            formatRuntimeFailure: (event, capability) => options.formatOutput(event, runtimeFailureResult(capability, options.registrations))
+        }
+    };
+}
+const AGENTS_ROUTING = {
+    desired: "## Loop Engineering\n\nLoad `.agent-ops/AGENTS.md` as the agent-ops managed baseline.\nProject-specific instructions in this file remain authoritative.\n",
+    legacy: [
+        "## Loop Engineering\n\nUse `.agent-ops/AGENTS.md` as the canonical Loop Engineering specification for this project.\n"
+    ]
+};
+const CLAUDE_ROUTING = {
+    desired: "## Loop Engineering\n\nLoad `.agent-ops/CLAUDE.md` as the agent-ops managed baseline.\nProject-specific instructions in this file remain authoritative.\n",
+    legacy: [
+        "## Loop Engineering\n\nUse `.agent-ops/CLAUDE.md` as the canonical Loop Engineering specification for this project.\n"
+    ]
+};
+const DESCRIPTORS = {
+    codex: createJsonDescriptor({
+        id: "codex",
+        instructionFile: "AGENTS.md",
+        routing: AGENTS_ROUTING,
+        hookPath: ".codex/hooks.json",
+        surfaces: codexSurfaces,
+        ownSettingsKeys: ["hooks", "description"],
+        buildHooks: (capabilities, runtimePath) => buildCodexHookConfig(capabilities, runtimePath),
+        mergeHooks: (existing, managed) => mergeCodexHookConfig(existing, managed),
+        stripHooks: (existing) => stripCodexManagedHooks(existing),
+        isManagedHandler: (handler) => isRecord(handler) &&
+            typeof handler.command === "string" &&
+            handler.command.includes(CODEX_MANAGED_MARKER),
+        registrations: CODEX_CAPABILITY_REGISTRATIONS,
+        normalizeInput: normalizeCodexHookInput,
+        formatOutput: (event, result) => {
+            const output = codexHookOutput(event, result);
+            return { exitCode: 0, stdout: output.stdout, stderr: "" };
+        }
+    }),
+    claude: createJsonDescriptor({
+        id: "claude",
+        instructionFile: "CLAUDE.md",
+        routing: CLAUDE_ROUTING,
+        hookPath: ".claude/settings.json",
+        surfaces: claudeSurfaces,
+        ownSettingsKeys: ["hooks"],
+        buildHooks: (capabilities, runtimePath) => buildClaudeHookSettings(capabilities, runtimePath),
+        mergeHooks: (existing, managed) => mergeClaudeSettings(existing, managed),
+        stripHooks: (existing) => stripClaudeManagedHooks(existing),
+        isManagedHandler: (handler) => isRecord(handler) &&
+            Array.isArray(handler.args) &&
+            handler.args.includes(CLAUDE_HOOK_MARKER),
+        registrations: CLAUDE_CAPABILITY_REGISTRATIONS,
+        normalizeInput: normalizeClaudeHookInput,
+        formatOutput: (event, result) => claudeHookOutput(event, result)
+    }),
+    opencode: {
+        id: "opencode",
+        control: {
+            instructionFile: "AGENTS.md",
+            routing: AGENTS_ROUTING,
+            hookPath: opencodePluginTarget("project").path,
+            hookPathForScope: (scope, root) => opencodePluginTarget(scope, root).path,
+            surfaces: opencodeSurfaces,
+            registrations: OPENCODE_CAPABILITY_REGISTRATIONS,
+            plan: (context) => planCommonHarnessContribution("opencode", context),
+            hookRegistered: (source, capabilities) => isOpencodePluginRegistered(source, capabilities)
+        },
+        runtime: {
+            normalizeInput: normalizeOpencodeHookInput,
+            formatOutput: (event, result) => opencodeHookOutput(event, result),
+            formatRuntimeFailure: (event, capability) => opencodeHookOutput(event, runtimeFailureResult(capability, OPENCODE_CAPABILITY_REGISTRATIONS))
+        }
+    }
+};
+export function harnessDescriptor(id) {
+    const descriptor = DESCRIPTORS[id];
+    if (descriptor === undefined) {
+        throw new AgentOpsError("HARNESS_ADAPTER_MISSING", `Missing harness adapter: ${id}`);
+    }
+    return descriptor;
+}
+export function harnessHookPath(id, scope, root) {
+    const descriptor = harnessDescriptor(id);
+    return descriptor.control.hookPathForScope?.(scope, root) ??
+        descriptor.control.hookPath;
+}
+export function harnessSurfaces(id, scope, root) {
+    return harnessDescriptor(id).control.surfaces(scope, root);
+}
+export function harnessSurfaceById(id, scope, surfaceId, root) {
+    return harnessSurfaces(id, scope, root).find((surface) => surface.id === surfaceId);
+}
+export function harnessSurfaceByPath(id, scope, path, root) {
+    return harnessSurfaces(id, scope, root).find((surface) => surface.path === path);
+}
+export function selectHarnessHookSurface(options) {
+    const descriptor = harnessDescriptor(options.harness);
+    if (descriptor.control.buildHooks === undefined) {
+        throw new AgentOpsError("HOOK_TARGET_UNSUPPORTED", `Harness hook targets are not supported for ${options.harness}.`);
+    }
+    const surfaces = harnessSurfaces(options.harness, options.scope, options.root);
+    const selected = options.surfaceId === undefined
+        ? options.persistedPath === undefined
+            ? surfaces.find((surface) => surface.access === "managed-default" &&
+                surface.representation === "json")
+            : findSurfaceByPath(surfaces, options.persistedPath)
+        : findSurfaceById(surfaces, options.surfaceId);
+    if (selected === undefined ||
+        selected.scope !== options.scope ||
+        !isWritableSurface(selected) ||
+        selected.representation !== "json") {
+        const requested = options.surfaceId ?? options.persistedPath ?? "default surface";
+        throw new AgentOpsError("HOOK_TARGET_INVALID", `Harness hook target is not a writable ${options.scope} surface: ${options.harness}=${requested}.`);
+    }
+    return selected;
+}
+export function isHarnessId(value) {
+    return Object.hasOwn(DESCRIPTORS, value);
+}
+/**
+ * `both` predates opencode and remains an input alias. `all` follows the
+ * registry and selects every registered harness.
+ */
+const HARNESS_ALIASES = {
+    all: HARNESS_IDS,
+    both: ["codex", "claude"]
+};
+export function resolveHarnessSelection(value) {
+    const alias = HARNESS_ALIASES[value.trim()];
+    if (alias !== undefined) {
+        return [...alias];
+    }
+    const ids = value.split(",").map((entry) => entry.trim());
+    return ids.length > 0 &&
+        ids.every(isHarnessId) &&
+        new Set(ids).size === ids.length
+        ? ids
+        : null;
+}
+export const COMMON_AGENTS_BLOCK = DESCRIPTORS.codex.control.routing.desired;
+export const COMMON_CLAUDE_BLOCK = DESCRIPTORS.claude.control.routing.desired;
+function managedRules(descriptor, context) {
     const lines = [
         "# Loop Engineering",
         "",
@@ -22,44 +249,75 @@ function managedRules(id, context) {
         lines.push("Advisory lifecycle summaries and local logs are informational. Advisory", "failures must remain fail-open and cannot become verification evidence.", "");
     }
     if (context.capabilities.includes("command-policy")) {
-        lines.push("Command policy guards high-confidence unsafe actions. Optional Stop", "verification never marks a task complete by itself.", "");
+        lines.push("Command policy guards high-confidence unsafe actions. Explicitly enabled", "Stop verification is report-only and never marks a task complete by itself.", "");
     }
-    lines.push(`This file is routed from the active ${instructionFile}.`, "");
+    lines.push(`This file is routed from the active ${descriptor.control.instructionFile}.`, "");
     return lines.join("\n");
 }
+function instructionStem(instructionFile) {
+    return instructionFile.replace(/\.md$/iu, "").toLowerCase();
+}
+export function rulesArtifactId(descriptor) {
+    return `${instructionStem(descriptor.control.instructionFile)}-rules`;
+}
+export function routingBlockId(id, scope, descriptor = harnessDescriptor(id)) {
+    return scope === "project" && descriptor.control.instructionFile === "AGENTS.md"
+        ? "agents-routing"
+        : `${id}-routing`;
+}
+function dedupeByPath(entries) {
+    const kept = [];
+    for (const entry of entries) {
+        const duplicate = kept.some((existing) => existing.path === entry.path && existing.content === entry.content);
+        if (!duplicate) {
+            kept.push(entry);
+        }
+    }
+    return kept;
+}
+async function planCommonHarnessContribution(id, context) {
+    const descriptor = harnessDescriptor(id);
+    const artifacts = [
+        {
+            id: rulesArtifactId(descriptor),
+            path: `.agent-ops/${descriptor.control.instructionFile}`,
+            content: managedRules(descriptor, context)
+        }
+    ];
+    if (id === "opencode" && context.runtimePath !== undefined) {
+        const plugin = buildOpencodePlugin(context.capabilities, context.runtimePath);
+        if (plugin !== null) {
+            artifacts.push({
+                id: "opencode-plugin",
+                path: context.opencodePluginPath ??
+                    opencodePluginTarget(context.scope, context.root).path,
+                content: plugin
+            });
+        }
+    }
+    return {
+        artifacts,
+        blocks: [
+            {
+                id: routingBlockId(id, context.scope, descriptor),
+                path: context.scope === "project"
+                    ? descriptor.control.instructionFile
+                    : `.${id}/${descriptor.control.instructionFile}`,
+                version: 1,
+                content: descriptor.control.routing.desired
+            }
+        ]
+    };
+}
 export function commonHarnessAdapters() {
-    return ["codex", "claude"].map((id) => {
-        const instructionFile = id === "codex" ? "AGENTS.md" : "CLAUDE.md";
-        const blockContent = id === "codex" ? COMMON_AGENTS_BLOCK : COMMON_CLAUDE_BLOCK;
+    return HARNESS_IDS.map((id) => {
+        const descriptor = harnessDescriptor(id);
         return {
             id,
-            async plan(context) {
-                return {
-                    artifacts: [
-                        {
-                            id: `${id}-rules`,
-                            path: `.agent-ops/${instructionFile}`,
-                            content: managedRules(id, context)
-                        }
-                    ],
-                    blocks: [
-                        {
-                            id: `${id}-routing`,
-                            path: context.scope === "project"
-                                ? instructionFile
-                                : `.${id}/${instructionFile}`,
-                            version: 1,
-                            content: blockContent
-                        }
-                    ]
-                };
-            }
+            plan: (context) => descriptor.control.plan(context)
         };
     });
 }
-export function requestedHarnessIds(harness) {
-    return harness === "both" ? ["codex", "claude"] : [harness];
-}
 function selectAdapter(id, adapters) {
     const matches = adapters.filter((adapter) => adapter.id === id);
     if (matches.length === 0) {
@@ -75,7 +333,7 @@ function selectAdapter(id, adapters) {
     return adapter;
 }
 export async function planHarnessContributions(harness, context, adapters) {
-    const selectedAdapters = requestedHarnessIds(harness).map((id) => selectAdapter(id, adapters));
+    const selectedAdapters = harness.map((id) => selectAdapter(id, adapters));
     const artifacts = [];
     const blocks = [];
     for (const adapter of selectedAdapters) {
@@ -83,5 +341,8 @@ export async function planHarnessContributions(harness, context, adapters) {
         artifacts.push(...contribution.artifacts);
         blocks.push(...contribution.blocks);
     }
-    return { artifacts, blocks };
+    return {
+        artifacts: dedupeByPath(artifacts),
+        blocks: dedupeByPath(blocks)
+    };
 }

package/dist/runtime/src/install/hooks.js

@@ -1,6 +1,5 @@
-import { buildClaudeHookSettings, mergeClaudeSettings, stripClaudeManagedHooks } from "../adapters/claude/config.js";
-import { buildCodexHookConfig, mergeCodexHookConfig, stripCodexManagedHooks } from "../adapters/codex/config.js";
 import { AgentOpsError } from "../fs/paths.js";
+import { harnessDescriptor, harnessHookPath } from "./harness.js";
 export const CLAUDE_HOOK_PATH = ".claude/settings.json";
 export const CODEX_HOOK_PATH = ".codex/hooks.json";
 function format(value) {
@@ -17,31 +16,34 @@ function parseSettings(path, source) {
         throw new AgentOpsError("HOOK_SETTINGS_INVALID_JSON", `Hook settings are not valid JSON: ${path}`, { cause: error });
     }
 }
-export function hookRegistrationPath(harness, scope) {
+export function hookRegistrationPath(harness, scope, root) {
     // ponytail: user scope resolves against AGENT_OPS_HOME, so the same
-    // relative path serves both scopes.
-    void scope;
-    return harness === "claude" ? CLAUDE_HOOK_PATH : CODEX_HOOK_PATH;
+    // root can resolve a scope-specific harness path.
+    return harnessHookPath(harness, scope, root);
 }
 /**
  * Builds the merged settings file for one harness, preserving foreign hooks.
  * Returns null when the selected capabilities register no events at all.
  */
 export function planHookRegistration(options) {
-    const path = hookRegistrationPath(options.harness, options.scope);
-    const managed = options.harness === "claude"
-        ? buildClaudeHookSettings(options.capabilities, options.runtimePath)
-        : buildCodexHookConfig(options.capabilities);
+    const descriptor = harnessDescriptor(options.harness);
+    if (descriptor.control.buildHooks === undefined ||
+        descriptor.control.mergeHooks === undefined) {
+        // File-backed adapters (currently opencode) track their plugin as a
+        // managed artifact rather than as a ManagedHookRecord.
+        return null;
+    }
+    const path = options.path ?? hookRegistrationPath(options.harness, options.scope);
+    const managed = descriptor.control.buildHooks(options.capabilities, options.runtimePath);
     const events = Object.keys(managed.hooks);
     if (events.length === 0) {
         return null;
     }
     const existing = parseSettings(path, options.currentSource);
-    const merged = options.harness === "claude"
-        ? mergeClaudeSettings(existing, managed)
-        : mergeCodexHookConfig(existing, managed);
+    const merged = descriptor.control.mergeHooks(existing, managed);
     return {
         content: format(merged),
+        disclosure: "opaque",
         record: {
             id: `${options.harness}-hooks`,
             path,
@@ -52,7 +54,7 @@ export function planHookRegistration(options) {
     };
 }
 function onlyManagedRemains(harness, value) {
-    const ownKeys = new Set(harness === "codex" ? ["hooks", "description"] : ["hooks"]);
+    const ownKeys = new Set(harnessDescriptor(harness).control.ownSettingsKeys ?? []);
     const hooks = value.hooks;
     return (Object.keys(value).every((key) => ownKeys.has(key)) &&
         typeof hooks === "object" &&
@@ -64,12 +66,15 @@ function onlyManagedRemains(harness, value) {
  * when nothing but agent-ops content is left, so foreign settings survive.
  */
 export function planHookRemoval(record, currentSource) {
+    const descriptor = harnessDescriptor(record.harness);
+    if (descriptor.control.stripHooks === undefined) {
+        throw new AgentOpsError("HOOK_REMOVAL_UNSUPPORTED", `Harness hook records are not supported for ${record.harness}.`);
+    }
     const existing = parseSettings(record.path, currentSource);
-    const stripped = record.harness === "claude"
-        ? stripClaudeManagedHooks(existing)
-        : stripCodexManagedHooks(existing);
+    const stripped = descriptor.control.stripHooks(existing);
     return {
         path: record.path,
+        disclosure: "opaque",
         content: onlyManagedRemains(record.harness, stripped)
             ? null
             : format(stripped)

package/dist/runtime/src/install/ownership.js

@@ -1,27 +1,24 @@
 import { applyManagedBlock, managedBlockMarkers } from "../fs/managed-block.js";
 import { AgentOpsError } from "../fs/paths.js";
-import { COMMON_AGENTS_BLOCK, COMMON_CLAUDE_BLOCK } from "./harness.js";
-import { hookRegistrationPath } from "./hooks.js";
-function selectedHarnesses(manifest) {
-    return manifest.harness === "both"
-        ? ["codex", "claude"]
-        : [manifest.harness];
-}
-function expectedMarker(manifest, id) {
-    const isCodex = id === "codex";
-    const markerId = `${id}-routing`;
+import { harnessDescriptor, harnessHookPath, routingBlockId, selectHarnessHookSurface, rulesArtifactId } from "./harness.js";
+import { isOpencodePluginPath } from "../adapters/opencode/config.js";
+function expectedMarker(manifest, id, markerId) {
+    const descriptor = harnessDescriptor(id);
     const markers = managedBlockMarkers(markerId, 1);
-    const instructionFile = isCodex ? "AGENTS.md" : "CLAUDE.md";
     return {
         id: markerId,
         path: manifest.scope === "project"
-            ? instructionFile
-            : `.${id}/${instructionFile}`,
+            ? descriptor.control.instructionFile
+            : `.${id}/${descriptor.control.instructionFile}`,
         startMarker: markers.start,
         endMarker: markers.end,
-        content: isCodex ? COMMON_AGENTS_BLOCK : COMMON_CLAUDE_BLOCK
+        content: descriptor.control.routing.desired,
+        legacyContent: descriptor.control.routing.legacy
     };
 }
+function pathKey(path) {
+    return path.toLowerCase();
+}
 function manifestOwnershipError() {
     return new AgentOpsError("MANIFEST_OWNERSHIP_INVALID", "The manifest does not match a supported managed installation shape.");
 }
@@ -29,37 +26,109 @@ function manifestOwnershipError() {
  * Hook records are optional: installations without hook capabilities, and
  * manifests written before hook registration existed, carry none.
  */
-function assertSupportedHookRecords(manifest, harnesses) {
+function assertSupportedHookRecords(manifest, harnesses, root) {
     const selected = new Set(harnesses);
     const seen = new Set();
     for (const hook of manifest.hooks ?? []) {
         if (!selected.has(hook.harness) ||
             seen.has(hook.harness) ||
+            harnessDescriptor(hook.harness).control.buildHooks === undefined ||
             hook.id !== `${hook.harness}-hooks` ||
-            hook.path !== hookRegistrationPath(hook.harness, manifest.scope) ||
             hook.events.length === 0) {
             throw manifestOwnershipError();
         }
+        try {
+            selectHarnessHookSurface({
+                harness: hook.harness,
+                scope: manifest.scope,
+                root,
+                persistedPath: hook.path
+            });
+        }
+        catch {
+            throw manifestOwnershipError();
+        }
         seen.add(hook.harness);
     }
 }
-export function assertSupportedManifestOwnership(manifest) {
-    const harnesses = selectedHarnesses(manifest);
-    const expectedArtifacts = new Map([
-        ["config", ".agent-ops/config.json"]
+export function assertSupportedManifestOwnership(manifest, root) {
+    const harnesses = manifest.harness;
+    const expectedArtifactPaths = new Map([
+        [
+            pathKey(".agent-ops/config.json"),
+            { path: ".agent-ops/config.json", ids: new Set(["config"]) }
+        ]
+    ]);
+    const requiredArtifactPaths = new Set([
+        pathKey(".agent-ops/config.json")
     ]);
     const expectedMarkers = new Map();
+    const expectedMarkerPaths = new Set();
+    const recordedOpencodePluginPath = manifest.artifacts.find(({ id }) => id === "opencode-plugin")?.path;
+    if (recordedOpencodePluginPath !== undefined &&
+        (!harnesses.includes("opencode") ||
+            !isOpencodePluginPath(manifest.scope, recordedOpencodePluginPath))) {
+        throw manifestOwnershipError();
+    }
     for (const id of harnesses) {
-        expectedArtifacts.set(`${id}-rules`, `.agent-ops/${id === "codex" ? "AGENTS.md" : "CLAUDE.md"}`);
-        const marker = expectedMarker(manifest, id);
-        expectedMarkers.set(marker.id, marker);
+        const descriptor = harnessDescriptor(id);
+        const artifactPath = `.agent-ops/${descriptor.control.instructionFile}`;
+        const artifactKey = pathKey(artifactPath);
+        const artifactEntry = expectedArtifactPaths.get(artifactKey);
+        const artifactIds = artifactEntry?.ids ?? new Set();
+        artifactIds.add(rulesArtifactId(descriptor));
+        // Accept the PR 2 per-harness spelling while update rewrites it to the
+        // path-derived ID. This keeps already-installed manifests removable.
+        artifactIds.add(`${id}-rules`);
+        expectedArtifactPaths.set(artifactKey, {
+            path: artifactEntry?.path ?? artifactPath,
+            ids: artifactIds
+        });
+        requiredArtifactPaths.add(artifactKey);
+        const markerPath = manifest.scope === "project"
+            ? descriptor.control.instructionFile
+            : `.${id}/${descriptor.control.instructionFile}`;
+        const markerKey = pathKey(markerPath);
+        expectedMarkerPaths.add(markerKey);
+        const currentId = routingBlockId(id, manifest.scope, descriptor);
+        const markerIds = new Set([currentId, `${id}-routing`]);
+        for (const markerId of markerIds) {
+            expectedMarkers.set(markerId, expectedMarker(manifest, id, markerId));
+        }
+        if (id === "opencode") {
+            const pluginPath = recordedOpencodePluginPath ?? harnessHookPath(id, manifest.scope, root);
+            const pluginKey = pathKey(pluginPath);
+            const pluginEntry = expectedArtifactPaths.get(pluginKey);
+            if (pluginEntry !== undefined && pluginEntry.path !== pluginPath) {
+                throw manifestOwnershipError();
+            }
+            const pluginIds = pluginEntry?.ids ?? new Set();
+            pluginIds.add("opencode-plugin");
+            expectedArtifactPaths.set(pluginKey, {
+                path: pluginPath,
+                ids: pluginIds
+            });
+        }
     }
-    if (manifest.artifacts.length !== expectedArtifacts.size ||
-        manifest.markers.length !== expectedMarkers.size) {
+    const opencodePluginPath = harnesses.includes("opencode")
+        ? recordedOpencodePluginPath ??
+            harnessHookPath("opencode", manifest.scope, root)
+        : null;
+    const optionalArtifactCount = opencodePluginPath !== null &&
+        expectedArtifactPaths.has(pathKey(opencodePluginPath))
+        ? 1
+        : 0;
+    if ((manifest.artifacts.length !== requiredArtifactPaths.size &&
+        manifest.artifacts.length !== requiredArtifactPaths.size +
+            optionalArtifactCount) ||
+        manifest.markers.length !== expectedMarkerPaths.size) {
         throw manifestOwnershipError();
     }
     for (const artifact of manifest.artifacts) {
-        if (expectedArtifacts.get(artifact.id) !== artifact.path) {
+        const expected = expectedArtifactPaths.get(pathKey(artifact.path));
+        if (expected === undefined ||
+            expected.path !== artifact.path ||
+            !expected.ids.has(artifact.id)) {
             throw manifestOwnershipError();
         }
     }
@@ -72,7 +141,7 @@ export function assertSupportedManifestOwnership(manifest) {
             throw manifestOwnershipError();
         }
     }
-    assertSupportedHookRecords(manifest, harnesses);
+    assertSupportedHookRecords(manifest, harnesses, root);
     return expectedMarkers;
 }
 function exactMarkerCount(source, marker) {
@@ -92,13 +161,20 @@ export function assertExpectedManagedBlock(source, marker, expected) {
         startIndex >= endIndex) {
         throw new AgentOpsError("MANAGED_BLOCK_CHANGED", `Managed block boundaries changed after installation: ${marker.path}`);
     }
-    const expectedBlock = applyManagedBlock("", {
-        id: expected.id,
-        version: 1,
-        content: expected.content
-    }).replace(/\n$/u, "");
     const currentBlock = source.slice(startIndex, endIndex + marker.endMarker.length);
-    if (currentBlock !== expectedBlock) {
-        throw new AgentOpsError("MANAGED_BLOCK_CHANGED", `Managed block content changed after installation: ${marker.path}`);
+    const candidates = [
+        ["desired", expected.content],
+        ...expected.legacyContent.map((content) => ["legacy", content])
+    ];
+    for (const [kind, content] of candidates) {
+        const expectedBlock = applyManagedBlock("", {
+            id: expected.id,
+            version: 1,
+            content
+        }).replace(/\n$/u, "");
+        if (currentBlock === expectedBlock) {
+            return kind;
+        }
     }
+    throw new AgentOpsError("MANAGED_BLOCK_CHANGED", `Managed block content changed after installation: ${marker.path}`);
 }