@kylecheng3146/agent-ops 0.1.4 → 0.1.6

package/dist/runtime/src/verify/command-executor.js

@@ -0,0 +1,113 @@
+import { runVerificationCommand } from "./spawn.js";
+import { evaluateTestCount, parseTestCount } from "./test-count.js";
+function classifyTestCountCode(code) {
+    const classes = {
+        TEST_COUNT_BELOW_MINIMUM: "test-count-below-minimum",
+        TEST_COUNT_INVALID: "test-count-invalid",
+        TEST_COUNT_OK: "none",
+        TEST_COUNT_REQUIREMENT_INVALID: "test-count-requirement-invalid",
+        TEST_COUNT_UNPARSEABLE: "test-count-unparseable",
+        ZERO_TESTS: "zero-tests"
+    };
+    return classes[code];
+}
+function untrustedResult(commandId) {
+    return {
+        commandId,
+        status: "UNKNOWN",
+        failureClass: "repository-untrusted",
+        exitCode: null,
+        signal: null,
+        timedOut: false,
+        durationMs: 0,
+        stdout: "",
+        stderr: "",
+        stdoutTruncated: false,
+        stderrTruncated: false
+    };
+}
+function classifyCommand(command, spawned) {
+    if (command.evidence.kind === "file") {
+        return {
+            status: spawned.status === "PASS" ? "UNKNOWN" : spawned.status,
+            failureClass: spawned.status === "PASS"
+                ? "file-evidence-unsupported"
+                : spawned.failureClass,
+            testCount: null
+        };
+    }
+    if (command.evidence.kind !== "test-count") {
+        return {
+            status: spawned.status,
+            failureClass: spawned.failureClass,
+            testCount: null
+        };
+    }
+    const testCount = parseTestCount(`${spawned.stdout}\n${spawned.stderr}`);
+    if (spawned.status !== "PASS") {
+        return {
+            status: spawned.status,
+            failureClass: spawned.failureClass,
+            testCount
+        };
+    }
+    const evaluation = evaluateTestCount(testCount, command.evidence.minimum);
+    return {
+        status: evaluation.status,
+        failureClass: classifyTestCountCode(evaluation.code),
+        testCount: evaluation.testCount
+    };
+}
+function diagnostic(spawned) {
+    return spawned.stderr || spawned.stdout || spawned.failureClass;
+}
+export async function executeConfiguredCommand(command, options) {
+    let spawned;
+    if (!options.trusted) {
+        spawned = untrustedResult(command.id);
+    }
+    else {
+        const runOptions = {
+            cwd: options.cwd,
+            ...(options.runner === undefined
+                ? {}
+                : { runner: options.runner }),
+            ...(options.env === undefined ? {} : { env: options.env }),
+            ...(options.now === undefined ? {} : { now: options.now }),
+            ...(options.outputLimitBytes === undefined
+                ? {}
+                : { outputLimitBytes: options.outputLimitBytes }),
+            ...(options.terminationGraceMs === undefined
+                ? {}
+                : { terminationGraceMs: options.terminationGraceMs })
+        };
+        spawned = await runVerificationCommand(command, runOptions);
+    }
+    const classified = classifyCommand(command, spawned);
+    return {
+        commandId: command.id,
+        required: command.required,
+        status: classified.status,
+        failureClass: classified.failureClass,
+        exitCode: spawned.exitCode,
+        signal: spawned.signal,
+        timedOut: spawned.timedOut,
+        testCount: classified.testCount,
+        diagnostic: diagnostic(spawned),
+        stdout: spawned.stdout,
+        stderr: spawned.stderr,
+        stdoutTruncated: spawned.stdoutTruncated,
+        stderrTruncated: spawned.stderrTruncated
+    };
+}
+export function aggregateVerificationStatus(results) {
+    const required = results.filter((result) => result.required);
+    const gating = required.length > 0 ? required : results;
+    if (gating.some((result) => result.status === "FAIL")) {
+        return "FAIL";
+    }
+    if (gating.some((result) => result.status === "UNKNOWN")) {
+        return "UNKNOWN";
+    }
+    return "PASS";
+}

package/dist/runtime/src/verify/evidence.js

@@ -1,32 +1,12 @@
 import { join } from "node:path";
-import { SCHEMA_VERSION } from "../contracts.js";
+import { EVIDENCE_SCHEMA_VERSION } from "../contracts.js";
 import { sha256 } from "../fs/hash.js";
 import { AgentOpsError } from "../fs/paths.js";
+import { calculateConfigHash } from "../config/hash.js";
+export { calculateConfigHash } from "../config/hash.js";
 import { validateEvidence } from "../schema/validate.js";
 import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
 import { redactSecrets } from "../security/redact.js";
-function canonicalJson(value) {
-    if (value === null ||
-        typeof value === "boolean" ||
-        typeof value === "number" ||
-        typeof value === "string") {
-        return JSON.stringify(value);
-    }
-    if (Array.isArray(value)) {
-        return `[${value.map(canonicalJson).join(",")}]`;
-    }
-    if (typeof value === "object") {
-        const record = value;
-        return `{${Object.keys(record)
-            .sort()
-            .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
-            .join(",")}}`;
-    }
-    throw new AgentOpsError("CONFIG_HASH_INVALID", "Configuration contains an unsupported value.");
-}
-export function calculateConfigHash(config) {
-    return sha256(canonicalJson(config));
-}
 function redactRecord(record) {
     return Object.fromEntries(Object.entries(record).map(([key, value]) => [
         redactSecrets(key),
@@ -43,7 +23,7 @@ function validateBuiltEvidence(value) {
 }
 export function buildVerificationEvidence(input) {
     return validateBuiltEvidence({
-        schemaVersion: SCHEMA_VERSION,
+        schemaVersion: EVIDENCE_SCHEMA_VERSION,
         taskId: input.taskId,
         criterionId: input.criterionId,
         commandId: input.command.id,

package/dist/runtime/src/verify/service.js

@@ -3,55 +3,11 @@ import { validateTaskAgainstConfig } from "../schema/validate.js";
 import { collectChangeSurface } from "./change-surface.js";
 import { buildVerificationEvidence } from "./evidence.js";
 import { createFailureFingerprint } from "./fingerprint.js";
+import { aggregateVerificationStatus, executeConfiguredCommand } from "./command-executor.js";
 import { selectVerificationScope } from "./scope.js";
-import { runVerificationCommand } from "./spawn.js";
-import { evaluateTestCount, parseTestCount } from "./test-count.js";
 function verificationError(code, message) {
     return new AgentOpsError(code, message);
 }
-function classifyTestCountCode(code) {
-    const classes = {
-        TEST_COUNT_BELOW_MINIMUM: "test-count-below-minimum",
-        TEST_COUNT_INVALID: "test-count-invalid",
-        TEST_COUNT_OK: "none",
-        TEST_COUNT_REQUIREMENT_INVALID: "test-count-requirement-invalid",
-        TEST_COUNT_UNPARSEABLE: "test-count-unparseable",
-        ZERO_TESTS: "zero-tests"
-    };
-    return classes[code];
-}
-function classifyResult(command, spawned) {
-    if (command.evidence.kind === "file") {
-        return {
-            status: spawned.status === "PASS" ? "UNKNOWN" : spawned.status,
-            failureClass: spawned.status === "PASS"
-                ? "file-evidence-unsupported"
-                : spawned.failureClass,
-            testCount: null
-        };
-    }
-    if (command.evidence.kind !== "test-count") {
-        return {
-            status: spawned.status,
-            failureClass: spawned.failureClass,
-            testCount: null
-        };
-    }
-    const testCount = parseTestCount(`${spawned.stdout}\n${spawned.stderr}`);
-    if (spawned.status !== "PASS") {
-        return {
-            status: spawned.status,
-            failureClass: spawned.failureClass,
-            testCount
-        };
-    }
-    const evaluation = evaluateTestCount(testCount, command.evidence.minimum);
-    return {
-        status: evaluation.status,
-        failureClass: classifyTestCountCode(evaluation.code),
-        testCount: evaluation.testCount
-    };
-}
 function exitCategory(result) {
     if (result.timedOut) {
         return "timeout";
@@ -64,17 +20,6 @@ function exitCategory(result) {
     }
     return result.exitCode === 0 ? "exit-zero" : "nonzero-exit";
 }
-function overallStatus(results) {
-    const required = results.filter((result) => result.required);
-    const gating = required.length > 0 ? required : results;
-    if (gating.some((result) => result.status === "FAIL")) {
-        return "FAIL";
-    }
-    if (gating.some((result) => result.status === "UNKNOWN")) {
-        return "UNKNOWN";
-    }
-    return "PASS";
-}
 function relevantCriteria(task, commandId) {
     return task.criteria.filter((criterion) => criterion.verifierIds.includes(commandId));
 }
@@ -85,9 +30,6 @@ function commandById(config, commandId) {
     }
     return command;
 }
-function diagnostics(spawned) {
-    return spawned.stderr || spawned.stdout || spawned.failureClass;
-}
 export class VerificationService {
     #options;
     constructor(options) {
@@ -120,51 +62,37 @@ export class VerificationService {
     }
     async #runCommand(task, command) {
         const startedAt = (this.#options.now ?? (() => new Date().toISOString()))();
-        const spawned = this.#options.trusted
-            ? await runVerificationCommand(command, {
-                cwd: await this.#commandCwd(command),
-                runner: this.#options.processRunner
-            })
-            : {
-                commandId: command.id,
-                status: "UNKNOWN",
-                failureClass: "repository-untrusted",
-                exitCode: null,
-                signal: null,
-                timedOut: false,
-                durationMs: 0,
-                stdout: "",
-                stderr: "",
-                stdoutTruncated: false,
-                stderrTruncated: false
-            };
-        const classified = classifyResult(command, spawned);
-        const fingerprint = classified.status === "PASS"
+        const result = await executeConfiguredCommand(command, {
+            cwd: await this.#commandCwd(command),
+            runner: this.#options.processRunner,
+            trusted: this.#options.trusted
+        });
+        const fingerprint = result.status === "PASS"
             ? null
             : createFailureFingerprint({
                 commandId: command.id,
-                failureClass: classified.failureClass,
-                exitCategory: spawned.timedOut
+                failureClass: result.failureClass,
+                exitCategory: result.timedOut
                     ? "timeout"
-                    : spawned.signal !== null
+                    : result.signal !== null
                         ? "signal-exit"
-                        : spawned.exitCode === null
+                        : result.exitCode === null
                             ? "no-exit"
-                            : spawned.exitCode === 0
+                            : result.exitCode === 0
                                 ? "exit-zero"
                                 : "nonzero-exit",
-                diagnostics: diagnostics(spawned)
+                diagnostics: result.diagnostic
             });
         const finishedAt = (this.#options.now ?? (() => new Date().toISOString()))();
-        const evidenceReferences = await this.#persistEvidence(task, command, startedAt, finishedAt, classified, spawned.exitCode);
+        const evidenceReferences = await this.#persistEvidence(task, command, startedAt, finishedAt, result, result.exitCode);
         return {
             commandId: command.id,
             required: command.required,
-            status: classified.status,
-            failureClass: classified.failureClass,
-            exitCode: spawned.exitCode,
-            timedOut: spawned.timedOut,
-            testCount: classified.testCount,
+            status: result.status,
+            failureClass: result.failureClass,
+            exitCode: result.exitCode,
+            timedOut: result.timedOut,
+            testCount: result.testCount,
             diagnostic: fingerprint?.diagnostics ?? "",
             evidenceReferences
         };
@@ -185,7 +113,7 @@ export class VerificationService {
         for (const commandId of selection.verifierIds) {
             results.push(await this.#runCommand(validation.value, commandById(this.#options.config, commandId)));
         }
-        const status = overallStatus(results);
+        const status = aggregateVerificationStatus(results);
         let signal = null;
         if (status === "PASS") {
             await this.#options.taskService.clearFailure(taskId);

package/dist/runtime/src/verify/spawn.js

@@ -138,6 +138,10 @@ export class NodeVerificationProcessRunner {
         const child = spawn(request.command, [...request.args], {
             cwd: request.cwd,
             detached: this.#platform !== "win32",
+            env: {
+                ...process.env,
+                ...(request.env ?? {})
+            },
             shell: request.shell,
             stdio: ["ignore", "pipe", "pipe"],
             windowsHide: true
@@ -258,7 +262,8 @@ export async function runVerificationCommand(command, options) {
             command: command.command,
             args: [...command.args],
             cwd: options.cwd,
-            shell: command.shell === true
+            shell: command.shell === true,
+            ...(options.env === undefined ? {} : { env: options.env })
         });
     }
     catch {

package/docs/en/guides/configuration.md

@@ -0,0 +1,159 @@
+# Configuration
+
+Keep project configuration explicit and layered. Choose scope, harness, and profile deliberately; do not infer trust or security exceptions from `--yes`.
+
+Use `--harness all` to select Codex, Claude Code, and opencode, or pass a
+comma-separated subset such as `codex,opencode`. `both` remains an input alias
+for the legacy Codex plus Claude selection.
+
+Project Codex and opencode installations share the managed supplemental
+`AGENTS.md` routing block and the `.agent-ops/AGENTS.md` rules artifact. The
+block loads the managed baseline while project-specific instructions remain
+authoritative. Claude uses the corresponding `CLAUDE.md` route and
+`.agent-ops/CLAUDE.md` artifact. Opencode additionally gets
+the agent-ops-owned `.opencode/plugins/agent-ops.js` file; `opencode.json` is
+never modified. The plugin is generated with the installed absolute runtime
+path, so update it through `agent-ops update` rather than editing it manually.
+
+At user scope, Codex and opencode keep separate routing files under `.codex/`
+and `.opencode/`; the global opencode plugin is placed under
+`.config/opencode/plugins/`, or under `$XDG_CONFIG_HOME/opencode/plugins/`
+when that variable points inside the managed user root. If OpenCode is
+configured with `$OPENCODE_CONFIG_DIR`, the plugin is placed under its
+`plugins/` directory instead. The installer discovers writable harness
+surfaces and applies the selected target policy; use
+`--hook-target <harness>=<surface-id>` when the managed default is not the
+intended surface. Project-local Claude hooks use `.claude/settings.json` by
+default; select `.claude/settings.local.json` explicitly when that is the
+intended surface.
+Advisory and guardrail hooks are registered only when the selected profile
+implies them. Advisory runs through the real SessionStart path and is
+fail-open. Claude and Codex lifecycle support is `supported`; OpenCode begins
+at app initialization and is honestly reported as `degraded`.
+
+### Project-local loop profile
+
+`--profile loop` is an opt-in project-scope profile. Select `codex`, `claude`,
+or both (for example, `--harness codex,claude`); it requires a
+POSIX-compatible `bash` and does not support Windows launchers yet. Start with
+a dry run:
+
+```bash
+agent-ops init --dry-run --scope project --harness codex,claude --profile loop --json
+agent-ops init --scope project --harness codex,claude --profile loop --yes
+```
+
+For each selected supported harness, agent-ops owns exactly one small launcher:
+`.codex/hooks/agent-ops-loop.sh` or `.claude/hooks/agent-ops-loop.sh`. Both
+launchers delegate to the same installed Node runtime, so they do not copy a
+project-specific loop script. Codex also gets `.codex/config.toml` only when it
+is absent. First installation seeds, without replacing existing content,
+`loop-goal.md`, `loop-state.md`, and `loop-telemetry.jsonl` under the selected
+harness directory. A hash-commented `.gitignore` block ignores those local
+files.
+
+The loop runs `SessionStart`, `UserPromptSubmit`, `PreToolUse`,
+`PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`,
+`SubagentStart`, and `SubagentStop`, but never adds `Stop`. It blocks only
+high-confidence literal secrets in prompts or Bash commands, plus dangerous
+Bash commands (including broad recursive deletion and `git reset --hard`). Codex uses its native
+exit-code blocking mechanism; Claude Code receives its documented native JSON
+decision shape. A `PermissionRequest`, including
+`sandbox_permissions: "require_escalated"`, only records an outcome and emits
+no allow or deny decision, preserving the host's normal approval flow.
+
+Session context, telemetry, and compaction state are deliberately bounded.
+Telemetry contains only timestamp, event, outcome, and rule identifier—not raw
+prompts, commands, or credentials—and rotates by byte size. A pre-compaction
+Git-status snapshot is redacted and written into a dedicated block in
+`loop-state.md`, leaving surrounding user content intact. Installer update and
+uninstall own only the launchers, native handler registrations, and exact
+`.gitignore` block; goals, state, telemetry, and `config.toml` remain local
+user files. If an existing `.codex/config.toml` explicitly says
+`[features]` then `hooks = false`, planning stops with
+`CODEX_LOOP_HOOKS_DISABLED` before any write.
+
+Codex and Claude Code require their normal project-hook trust/review flow for
+these generated handlers. The loop is a focused guardrail, not a complete
+sandbox, permission bypass, or Stop-verification feature. See the [Codex hook
+documentation](https://developers.openai.com/codex/config-advanced#hooks) and
+the [Claude Code hook documentation](https://code.claude.com/docs/en/hooks)
+before enabling it.
+
+### Runtime-failure safeguards
+
+For the ordinary `guardrails` profile, `command-policy` is the only capability with a fail-closed failure mode. Claude
+Code can emit its documented denial shape at native `PreToolUse` for a
+classified invalid installed configuration. The managed OpenCode
+`tool.execute.before` plugin can throw its documented command-policy denial or
+unavailable-runtime error for its supported Bash surface. Codex is explicitly
+non-enforcing (`unknown`). These are agent-ops output and plugin contracts, not
+proof that a host honors a denial. `SessionStart` and `Stop` failure paths stay
+fail-open for every adapter.
+
+Claude's invalid-config fallback has four safeguards: (1) an absent project
+configuration stays fail-open, so only an invalid `.agent-ops/config.json` can
+reach the fallback; (2) the manifest must safely prove that the current harness
+is installed; (3) a human can export `AGENT_OPS_DISABLE=1` in the shell before
+launching the host to restore fail-open temporarily; and (4) a Claude Code
+denial names the config path and tells the user to repair it or temporarily set
+that shell variable. The variable is read only from the hook-process environment
+and cannot be set in agent-ops configuration, a manifest, or managed files.
+
+`guardrails` installs command policy but does not enable Stop verification. Stop
+is a separate config-v2 feature and must be explicitly enabled with at least
+one confirmed command:
+
+```json
+{
+  "features": { "stopVerification": { "enabled": true } },
+  "verification": {
+    "commands": [
+      {
+        "id": "unit",
+        "command": "npm",
+        "args": ["test"],
+        "cwd": ".",
+        "required": true,
+        "evidence": { "kind": "test-count", "minimum": 1 }
+      }
+    ]
+  }
+}
+```
+
+Changing this feature changes native registration. Run:
+
+```bash
+agent-ops update
+agent-ops trust grant
+```
+
+Without `update`, doctor can report `UPDATE_REQUIRED` for registration drift.
+Separately, after a toolkit upgrade or effective profile or capability change
+alters an intact path-independent managed rules artifact,
+`artifact-staleness` reports `DEGRADED` with `UPDATE_REQUIRED`. `agent-ops
+update` regenerates the artifact and clears that result; a missing or
+hash-mismatched artifact remains an `artifacts` `FAIL`. Without the new trust
+grant, trust-gated hooks remain stale. Stop is report-only: it continues the
+harness for `PASS`, `FAIL`, or `UNKNOWN`, emits only bounded command ID, exit
+code, test-count, config-hash, and timestamp evidence, and never completes a
+task. Config v1 migrates deterministically to v2 with Stop disabled; old
+binaries cannot read the migrated config, and the routing migration is
+one-way after it is applied.
+
+To narrow an existing installation, pass the desired list to `agent-ops update
+--harness`; shared paths remain managed while removed harness-owned artifacts,
+markers, and hooks are reconciled.
+
+Installations using the previous canonical routing wording are migrated by
+`agent-ops update`. If a managed block was edited, the command fails closed
+until the change is reviewed.
+
+Dry-run human and JSON plans omit raw harness settings content. They expose the
+expected hash, content hash, and a safe summary while the internal apply plan
+retains the complete merged settings. The manifest remains schema v2.
+
+Use the [acceptance and evidence rules](../spec/acceptance-and-evidence.md)
+when adding verification commands, and the [adapter rules](../spec/harness-adapters.md)
+when configuring Codex, Claude Code, or opencode behavior.

package/docs/en/guides/quickstart.md

@@ -0,0 +1,9 @@
+# Quickstart
+
+1. Define 2–5 acceptance criteria.
+2. Inspect the smallest relevant scope.
+3. Run a failing test before implementation.
+4. Implement the smallest change, then run typecheck and tests.
+5. Record evidence and request independent review before handoff.
+
+See the [normative loop](../spec/loop-engineering.md) and [review rules](../spec/review.md).

package/docs/en/guides/security.md

@@ -0,0 +1,5 @@
+# Security
+
+Treat commands, logs, configuration, and external input as untrusted. Redact credentials, block destructive commands by default, and keep local state out of tracked project paths.
+
+Read the [guardrails](../spec/guardrails.md), [judgment rules](../spec/judgment.md), and [maintenance rules](../spec/maintenance.md) before changing policy or hook files.

package/docs/en/spec/README.md

@@ -2,6 +2,15 @@
 
 This is the normative English specification for bounded, evidence-driven work.
 
+The harness adapter rules cover Codex, Claude Code, and opencode. The opencode
+integration is a generated local plugin; it does not manage `opencode.json`.
+
+Configuration is versioned independently from the manifest. Config v1 migrates
+to config v2 with Stop verification disabled; changing the capability requires
+`agent-ops update` followed by `agent-ops trust grant`. Stop verification is
+explicit, trusted, report-only, and never completes a task. Dry-run plans keep
+foreign settings opaque, and the routing migration is one-way once applied.
+
 - [Loop engineering](./loop-engineering.md)
 - [Acceptance and evidence](./acceptance-and-evidence.md)
 - [Judgment](./judgment.md)

package/docs/en/spec/harness-adapters.md

@@ -1,12 +1,22 @@
 # Harness Adapters
 
+OpenCode plugin behavior in this document was checked against the [official
+plugin documentation](https://opencode.ai/docs/plugins/) and [Bun shell
+documentation](https://bun.sh/docs/runtime/shell) on 2026-07-31. Codex and
+Claude Code loop-hook behavior was checked against their [Codex hook
+documentation](https://developers.openai.com/codex/config-advanced#hooks) and
+[Claude Code hook documentation](https://code.claude.com/docs/en/hooks) on
+2026-08-03. Revalidate: when any vendor reference changes.
+
 ## HARNESS-ADAPTER-001
 
-An adapter MUST preserve native harness semantics and MUST label unsupported behavior as UNKNOWN.
+An adapter MUST preserve native harness semantics and MUST declare each
+capability as supported, degraded, unsupported, or unknown.
 
 - Trigger: Mapping portable lifecycle or review behavior into a native harness.
 - Action: Keep ownership narrow, retain user configuration, and document limitations.
-- Evidence: Adapter tests cover existing configuration and unsupported outcomes.
+- Evidence: Adapter tests cover existing configuration, support declarations,
+  and native failure outcomes.
 - Positive: `A Codex blocking outcome remains UNKNOWN when native denial is unconfirmed.`
 - Negative: `Assume Claude exit semantics apply to Codex.`
 
@@ -19,3 +29,95 @@ An adapter MUST be idempotent and MUST avoid deleting user-owned handlers.
 - Evidence: Existing configuration fixtures remain intact after apply and uninstall.
 - Positive: `Managed handler updates while unrelated handlers remain byte-for-byte present.`
 - Negative: `Replace the complete settings file with toolkit defaults.`
+
+## HARNESS-ADAPTER-003
+
+A file-backed adapter MUST register only hooks implied by the active
+capabilities and MUST track generated source as one whole-file artifact.
+
+- Trigger: Installing or probing a harness whose extension point is a plugin file.
+- Action: For opencode, manage `.opencode/plugins/agent-ops.js` in a project or `.config/opencode/plugins/agent-ops.js` at user scope (`$XDG_CONFIG_HOME/opencode/plugins/agent-ops.js` when configured inside the managed user root, or `$OPENCODE_CONFIG_DIR/plugins/agent-ops.js` when that native config directory is configured), leave `opencode.json` untouched, and deduplicate a project `AGENTS.md` contribution by path.
+- Evidence: The manifest contains the plugin hash, the generated source contains only the selected hook registrations, and shared project markers occur once.
+- Positive: `codex,opencode` produces one project AGENTS route and one hashed opencode plugin.
+- Negative: `Add an opencode.json instructions entry or register a plugin for a core-only profile.`
+
+## HARNESS-ADAPTER-004
+
+The opencode shim MUST invoke the absolute runtime path from the selected
+project directory, MUST fail open for
+advisory events, and MUST throw its documented command-policy error when the
+runtime is unavailable.
+
+- Trigger: The generated plugin invokes `agent-ops` or receives an invalid runtime decision.
+- Action: Keep normalization and native output encoding in the runtime adapter,
+  throw its documented policy reason for a deny decision, and run
+  lifecycle-summary through the shared advisory implementation. App-scoped
+  plugin initialization remains degraded for per-session lifecycle fidelity.
+- Evidence: Shim import tests cover allow, deny, and missing-runtime behavior;
+  denial fixtures assert output shape only; doctor reports OpenCode lifecycle
+  support as `DEGRADED`.
+- Positive: `When the runtime is unavailable, SessionStart stays fail-open and the generated plugin throws its documented command-policy error for a Bash pre-tool hook.`
+- Negative: `Fall back to a PATH-resolved agent-ops executable, claim an OpenCode host honors a thrown denial, or claim app initialization is a per-session Stop-equivalent.`
+
+## HARNESS-ADAPTER-005
+
+Each descriptor MUST expose separate control and runtime adapters. The control
+adapter owns installation planning, routing, ownership, probes, and the
+in-memory capability registration matrix. The runtime adapter owns native input
+decoding, normalized events, native output encoding, and runtime-failure output.
+
+- Trigger: Adding a harness surface or a generic capability.
+- Action: Add the capability-to-native registration to the owning harness,
+  including its support level and runtime-failure mode; do not add native
+  events to a universal union.
+- Evidence: Every declared `supported` registration is exercised through the
+  real CLI hook process; denial-shape fixtures assert documented wire shapes,
+  not host runtime enforcement; unsupported Stop/lifecycle registrations are
+  not reported as enforcement success.
+- Positive: `A fail-closed Claude command-policy runtime failure produces the documented PreToolUse denial shape through runHookCommand.`
+- Negative: `Mark SessionStart supported while dispatchHookEvent has no advisory implementation.`
+
+## HARNESS-ADAPTER-006
+
+The project-local `loop` profile MUST be opt-in, project scoped, and use one
+shared runtime behind minimal Codex and Claude Code launchers. It MUST NOT copy
+policy into project-specific scripts or alter an ordinary permission request.
+
+- Trigger: A project selects `loop` with Codex, Claude Code, or both.
+- Action: Generate only the selected `.codex/hooks/agent-ops-loop.sh` and/or
+  `.claude/hooks/agent-ops-loop.sh` launchers, register the documented loop
+  lifecycle events except `Stop`, and preserve foreign hook groups. Block only
+  high-confidence literal credentials at `UserPromptSubmit` or Bash
+  `PreToolUse`, and dangerous Bash commands at `PreToolUse`, using the documented native denial shape. Emit no
+  decision for `PermissionRequest`, including escalated permissions.
+- Evidence: Install-plan, loop-runtime, update, uninstall, and doctor tests
+  cover generated paths, Codex/Claude wire output, privacy bounds,
+  configuration conflict handling, state preservation, and registration drift.
+- Positive: `A Claude PreToolUse dangerous Bash command receives a native deny while a PermissionRequest produces no allow or deny decision.`
+- Negative: `Copy a project loop policy into both shell launchers, auto-approve sandbox escalation, or add a loop Stop handler.`
+
+The current registration matrix is intentionally asymmetric:
+
+| Capability | Codex | Claude Code | OpenCode |
+| --- | --- | --- | --- |
+| lifecycle-summary | supported | supported | degraded |
+| command-policy | unknown | supported | supported |
+| optional-stop-verify | unsupported | supported | degraded |
+
+For runtime-failure handling, only `command-policy` is fail-closed. Claude
+Code can emit its documented `PreToolUse` denial shape for a classified invalid
+installed configuration; the managed OpenCode `tool.execute.before` plugin can
+throw its documented denial or unavailable-runtime error for its supported Bash
+surface. Codex remains `unknown` and never emits a denial. Fixture tests assert
+these wire and plugin shapes only; they do not prove that a host honors a
+denial. Every `SessionStart` and `Stop` failure path remains fail-open.
+
+Stop verification is explicit, trusted, report-only, and disabled by default.
+Every Stop result continues the native harness and may carry only bounded
+command evidence; it is never task-completion evidence.
+
+The `loop` profile is separate from the ordinary capability matrix above. It
+stores only bounded local event metadata, returns bounded redacted session
+context, and preserves local goal, state, telemetry, and Codex TOML files on
+update or uninstall. A clearly parsed `[features]` / `hooks = false` in an
+existing Codex configuration MUST reject loop planning before any write.

package/docs/en/spec/maintenance.md

@@ -19,3 +19,14 @@ Volatile harness facts MUST live in adapter or research documentation and MUST i
 - Evidence: The document has a source and `Revalidate:` condition.
 - Positive: `Revalidate: when the vendor hook reference changes.`
 - Negative: `Treat a transient CLI flag as a permanent core rule.`
+
+## MAINTAIN-PLUGIN-001
+
+Generated harness plugins MUST be treated as managed artifacts and MUST NOT be
+hand-edited in place.
+
+- Trigger: Updating the runtime, capabilities, or a vendor plugin contract.
+- Action: Regenerate the opencode shim, verify its manifest hash, and revalidate the vendor behavior before release.
+- Evidence: The artifact hash and shim import tests pass; release documentation records the revalidation condition.
+- Positive: `agent-ops update` rewrites a changed plugin after ownership checks pass.
+- Negative: `Patch the opencode plugin manually and retain the old manifest hash.`