@kylecheng3146/agent-ops 0.1.5 → 0.1.6

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

@@ -1,4 +1,4 @@
-import { buildClaudeHookSettings, mergeClaudeSettings, stripClaudeManagedHooks } from "../adapters/claude/config.js";
+import { buildClaudeHookSettings, isClaudeManagedHandler, 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";
@@ -20,7 +20,6 @@ export const HARNESS_IDS = [
     "claude",
     "opencode"
 ];
-const CLAUDE_HOOK_MARKER = "--managed-by=agent-ops";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -60,12 +59,13 @@ function jsonHookRegistered(control, source, capabilities) {
                 group.hooks.some(control.isManagedHandler)));
     });
 }
-function runtimeFailureResult(capability, registrations) {
+function runtimeFailureResult(capability, registrations, remedy) {
     const runtimeFailure = registrations.find((registration) => registration.capability === capability)?.runtimeFailure;
     return {
         action: runtimeFailure === "fail-closed" ? "block" : "continue",
         status: "UNKNOWN",
-        code: `${capability.replaceAll("-", "_").toUpperCase()}_UNAVAILABLE`
+        code: `${capability.replaceAll("-", "_").toUpperCase()}_UNAVAILABLE`,
+        ...(remedy === undefined ? {} : { remedy })
     };
 }
 function createJsonDescriptor(options) {
@@ -89,7 +89,7 @@ function createJsonDescriptor(options) {
         runtime: {
             normalizeInput: options.normalizeInput,
             formatOutput: options.formatOutput,
-            formatRuntimeFailure: (event, capability) => options.formatOutput(event, runtimeFailureResult(capability, options.registrations))
+            formatRuntimeFailure: (event, capability, remedy) => options.formatOutput(event, runtimeFailureResult(capability, options.registrations, remedy))
         }
     };
 }
@@ -136,9 +136,7 @@ const DESCRIPTORS = {
         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),
+        isManagedHandler: isClaudeManagedHandler,
         registrations: CLAUDE_CAPABILITY_REGISTRATIONS,
         normalizeInput: normalizeClaudeHookInput,
         formatOutput: (event, result) => claudeHookOutput(event, result)
@@ -158,7 +156,7 @@ const DESCRIPTORS = {
         runtime: {
             normalizeInput: normalizeOpencodeHookInput,
             formatOutput: (event, result) => opencodeHookOutput(event, result),
-            formatRuntimeFailure: (event, capability) => opencodeHookOutput(event, runtimeFailureResult(capability, OPENCODE_CAPABILITY_REGISTRATIONS))
+            formatRuntimeFailure: (event, capability, remedy) => opencodeHookOutput(event, runtimeFailureResult(capability, OPENCODE_CAPABILITY_REGISTRATIONS, remedy))
         }
     }
 };
@@ -229,7 +227,7 @@ export function resolveHarnessSelection(value) {
 }
 export const COMMON_AGENTS_BLOCK = DESCRIPTORS.codex.control.routing.desired;
 export const COMMON_CLAUDE_BLOCK = DESCRIPTORS.claude.control.routing.desired;
-function managedRules(descriptor, context) {
+export function managedRules(descriptor, context) {
     const lines = [
         "# Loop Engineering",
         "",

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

@@ -2,9 +2,10 @@ import { applyManagedBlock, managedBlockMarkers } from "../fs/managed-block.js";
 import { AgentOpsError } from "../fs/paths.js";
 import { harnessDescriptor, harnessHookPath, routingBlockId, selectHarnessHookSurface, rulesArtifactId } from "./harness.js";
 import { isOpencodePluginPath } from "../adapters/opencode/config.js";
+import { LOOP_MARKER_ID, LOOP_MARKER_VERSION, loopIgnoreContent, loopLauncherArtifactId, loopLauncherPath, selectedLoopHarnesses } from "./codex-loop.js";
 function expectedMarker(manifest, id, markerId) {
     const descriptor = harnessDescriptor(id);
-    const markers = managedBlockMarkers(markerId, 1);
+    const markers = managedBlockMarkers(markerId, 1, "html");
     return {
         id: markerId,
         path: manifest.scope === "project"
@@ -12,10 +13,23 @@ function expectedMarker(manifest, id, markerId) {
             : `.${id}/${descriptor.control.instructionFile}`,
         startMarker: markers.start,
         endMarker: markers.end,
+        markerStyle: "html",
         content: descriptor.control.routing.desired,
         legacyContent: descriptor.control.routing.legacy
     };
 }
+function expectedLoopMarker(manifest) {
+    const markers = managedBlockMarkers(LOOP_MARKER_ID, LOOP_MARKER_VERSION, "hash");
+    return {
+        id: LOOP_MARKER_ID,
+        path: ".gitignore",
+        startMarker: markers.start,
+        endMarker: markers.end,
+        markerStyle: "hash",
+        content: loopIgnoreContent(manifest.harness),
+        legacyContent: []
+    };
+}
 function pathKey(path) {
     return path.toLowerCase();
 }
@@ -64,6 +78,14 @@ export function assertSupportedManifestOwnership(manifest, root) {
     ]);
     const expectedMarkers = new Map();
     const expectedMarkerPaths = new Set();
+    const loopHarnesses = selectedLoopHarnesses(harnesses);
+    const hasLoopArtifacts = manifest.artifacts.some(({ id }) => loopHarnesses.some((harness) => id === loopLauncherArtifactId(harness)));
+    const hasLoopMarker = manifest.markers.some(({ id }) => id === LOOP_MARKER_ID);
+    const hasLoop = hasLoopArtifacts || hasLoopMarker;
+    if (hasLoop &&
+        (manifest.scope !== "project" || loopHarnesses.length === 0)) {
+        throw manifestOwnershipError();
+    }
     const recordedOpencodePluginPath = manifest.artifacts.find(({ id }) => id === "opencode-plugin")?.path;
     if (recordedOpencodePluginPath !== undefined &&
         (!harnesses.includes("opencode") ||
@@ -110,6 +132,18 @@ export function assertSupportedManifestOwnership(manifest, root) {
             });
         }
     }
+    if (hasLoop) {
+        for (const harness of loopHarnesses) {
+            const path = loopLauncherPath(harness);
+            expectedArtifactPaths.set(pathKey(path), {
+                path,
+                ids: new Set([loopLauncherArtifactId(harness)])
+            });
+            requiredArtifactPaths.add(pathKey(path));
+        }
+        expectedMarkerPaths.add(pathKey(".gitignore"));
+        expectedMarkers.set(LOOP_MARKER_ID, expectedLoopMarker(manifest));
+    }
     const opencodePluginPath = harnesses.includes("opencode")
         ? recordedOpencodePluginPath ??
             harnessHookPath("opencode", manifest.scope, root)
@@ -170,7 +204,8 @@ export function assertExpectedManagedBlock(source, marker, expected) {
         const expectedBlock = applyManagedBlock("", {
             id: expected.id,
             version: 1,
-            content
+            content,
+            markerStyle: expected.markerStyle
         }).replace(/\n$/u, "");
         if (currentBlock === expectedBlock) {
             return kind;

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

@@ -7,6 +7,7 @@ import { AgentOpsError, resolveContainedPath } from "../fs/paths.js";
 import { validateConfig } from "../schema/validate.js";
 import { planHarnessContributions, harnessDescriptor, selectHarnessHookSurface } from "./harness.js";
 import { assertExpectedManagedBlock, assertSupportedManifestOwnership } from "./ownership.js";
+import { codexHooksExplicitlyDisabled, loopLauncherArtifactId, loopSeeds, planLoopContribution, selectedLoopHarnesses } from "./codex-loop.js";
 import { isOpencodeManagedPlugin } from "../adapters/opencode/config.js";
 import { planHookRegistration, planHookRemoval } from "./hooks.js";
 import { resolveCapabilities, resolveProfiles } from "./profiles.js";
@@ -116,7 +117,7 @@ function assertUniqueContributions(artifacts, blocks) {
     }
     const markerBoundaries = new Set();
     for (const block of blocks) {
-        const markers = managedBlockMarkers(block.id, block.version);
+        const markers = managedBlockMarkers(block.id, block.version, block.markerStyle);
         const key = pathKey(block.path);
         if (ids.has(block.id) ||
             artifactPaths.has(key) ||
@@ -198,9 +199,53 @@ async function planArtifactRemoval(root, artifact) {
         expectedHash: current.hash
     };
 }
+async function planCreateOnceSeeds(root, seeds) {
+    const operations = [];
+    for (const seed of seeds) {
+        const current = await readCurrentFile(root, seed.path);
+        if (current === null) {
+            operations.push({
+                kind: "write",
+                path: seed.path,
+                content: seed.content,
+                expectedHash: null
+            });
+        }
+    }
+    return operations;
+}
+/**
+ * User-owned seed files belong to the first loop install for each harness.
+ * An existing loop launcher is the durable installation record: it prevents an
+ * update from recreating a file a user intentionally removed, while still
+ * allowing loop to be enabled later or for a newly added harness.
+ */
+function loopHarnessesNeedingSeeds(harnesses, existingManifest) {
+    const existingArtifactIds = new Set(existingManifest?.artifacts.map(({ id }) => id) ?? []);
+    return selectedLoopHarnesses(harnesses).filter((harness) => !existingArtifactIds.has(loopLauncherArtifactId(harness)));
+}
 function markerKey(path, id) {
     return `${pathKey(path)}\0${id}`;
 }
+function assertLoopProfileSupport(scope, harness, capabilities) {
+    if (!capabilities.includes("project-loop")) {
+        return;
+    }
+    if (scope !== "project" ||
+        !harness.some((id) => id === "codex" || id === "claude")) {
+        throw new AgentOpsError("LOOP_PROFILE_UNSUPPORTED", "The loop profile requires project scope and the Codex or Claude harness.");
+    }
+}
+async function assertCodexLoopConfiguration(root, harness, capabilities) {
+    if (!capabilities.includes("project-loop") ||
+        !harness.includes("codex")) {
+        return;
+    }
+    const config = await readCurrentFile(root, ".codex/config.toml");
+    if (config !== null && codexHooksExplicitlyDisabled(config.content)) {
+        throw new AgentOpsError("CODEX_LOOP_HOOKS_DISABLED", "Codex loop installation requires [features] hooks = true; the existing .codex/config.toml explicitly disables hooks.");
+    }
+}
 async function planBlocks(root, blocks, removals = [], expectedMarkers = new Map()) {
     const grouped = new Map();
     for (const block of blocks) {
@@ -238,7 +283,7 @@ async function planBlocks(root, blocks, removals = [], expectedMarkers = new Map
                 throw new AgentOpsError("MANIFEST_OWNERSHIP_INVALID", "The manifest contains an unsupported managed block.");
             }
             assertExpectedManagedBlock(content, marker, expected);
-            content = removeManagedBlock(content, marker.id);
+            content = removeManagedBlock(content, marker.id, expected.markerStyle);
         }
         for (const block of pathBlocks) {
             content = applyManagedBlock(content, block);
@@ -260,7 +305,7 @@ async function planBlocks(root, blocks, removals = [], expectedMarkers = new Map
             });
         }
         for (const block of pathBlocks) {
-            const markers = managedBlockMarkers(block.id, block.version);
+            const markers = managedBlockMarkers(block.id, block.version, block.markerStyle);
             records.push({
                 id: block.id,
                 path,
@@ -282,6 +327,8 @@ export async function createInstallPlan(options) {
     const resolved = options.existingConfig === undefined
         ? resolveProfiles(options.profiles)
         : resolveCapabilities(options.existingConfig.value);
+    assertLoopProfileSupport(options.scope, options.harness, resolved.capabilities);
+    await assertCodexLoopConfiguration(options.root, options.harness, resolved.capabilities);
     const existing = await readExistingManifest(options.root);
     assertCompatibleManifest(existing?.manifest ?? null, options.scope, options.harness, options.allowHarnessChange === true);
     const existingOpencodePluginPath = existing?.manifest.artifacts.find(({ id }) => id === "opencode-plugin")?.path;
@@ -300,7 +347,7 @@ export async function createInstallPlan(options) {
         explicitHookTargets.size > 0) {
         throw new AgentOpsError("HOOK_TARGET_REQUIRES_RUNTIME", "An explicit hook target requires a hook runtime path.");
     }
-    const contribution = await planHarnessContributions(options.harness, {
+    const baseContribution = await planHarnessContributions(options.harness, {
         root: options.root,
         scope: options.scope,
         profiles: resolved.profiles,
@@ -315,6 +362,21 @@ export async function createInstallPlan(options) {
             ? {}
             : { opencodePluginPath: existingOpencodePluginPath })
     }, options.adapters);
+    const loopContribution = planLoopContribution({
+        scope: options.scope,
+        harnesses: options.harness,
+        capabilities: resolved.capabilities,
+        ...(options.hookRuntimePath === undefined
+            ? {}
+            : { hookRuntimePath: options.hookRuntimePath })
+    });
+    const contribution = {
+        artifacts: [
+            ...baseContribution.artifacts,
+            ...loopContribution.artifacts
+        ],
+        blocks: [...baseContribution.blocks, ...loopContribution.blocks]
+    };
     assertUniqueContributions(contribution.artifacts, contribution.blocks);
     const reconcileExisting = existing !== null;
     const expectedExistingMarkers = reconcileExisting
@@ -359,6 +421,10 @@ export async function createInstallPlan(options) {
         operations.push(planned.operation);
         artifacts.push(planned.record);
     }
+    if (resolved.capabilities.includes("project-loop")) {
+        const seedHarnesses = loopHarnessesNeedingSeeds(options.harness, existing?.manifest ?? null);
+        operations.push(...await planCreateOnceSeeds(options.root, loopSeeds(seedHarnesses)));
+    }
     artifacts.push(...preservedArtifacts);
     for (const artifact of artifactsToRemove) {
         operations.push(await planArtifactRemoval(options.root, artifact));

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

@@ -1,16 +1,18 @@
 import { AgentOpsError } from "../fs/paths.js";
-const PROFILE_ORDER = ["core", "advisory", "guardrails"];
+const PROFILE_ORDER = ["core", "advisory", "guardrails", "loop"];
 export const PROFILE_CAPABILITIES = {
     core: ["rules", "task", "verify", "review"],
     advisory: ["lifecycle-summary", "local-log"],
-    guardrails: ["command-policy"]
+    guardrails: ["command-policy"],
+    loop: ["project-loop"]
 };
 export function resolveProfiles(inputProfiles) {
     if (inputProfiles.length === 0) {
         throw new AgentOpsError("PROFILE_REQUIRED", "At least one installation profile is required.");
     }
     const selectedProfiles = new Set(inputProfiles);
-    if (selectedProfiles.has("guardrails")) {
+    if (selectedProfiles.has("guardrails") ||
+        selectedProfiles.has("loop")) {
         selectedProfiles.add("core");
     }
     const profiles = PROFILE_ORDER.filter((profile) => selectedProfiles.has(profile));

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

@@ -86,7 +86,7 @@ async function planMarkerFiles(root, markers, expectedMarkers) {
             }
             assertExpectedManagedBlock(content, marker, expected);
             try {
-                content = removeManagedBlock(content, marker.id);
+                content = removeManagedBlock(content, marker.id, expected.markerStyle);
             }
             catch (error) {
                 throw new AgentOpsError("MANAGED_BLOCK_CHANGED", `Managed block cannot be removed safely: ${path}`, { cause: error });

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

@@ -9,6 +9,7 @@ import { createInstallPlan } from "./plan.js";
 const PACKAGE_NAME = "@kylecheng3146/agent-ops";
 const CONFIG_PATH = ".agent-ops/config.json";
 const MAX_UPDATE_CONFIG_BYTES = 1024 * 1024;
+const TOOLKIT_VERSION_PATTERN = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u;
 async function readBoundedConfig(root) {
     const resolvedPath = await resolveContainedPath(root, CONFIG_PATH);
     const before = await lstat(resolvedPath, { bigint: true });
@@ -82,6 +83,9 @@ export async function createUpdatePlan(options) {
     if (targetVersion === undefined) {
         throw new AgentOpsError("UPDATE_TARGET_REQUIRED", "Update requires a target version or an explicit registry client.");
     }
+    if (!TOOLKIT_VERSION_PATTERN.test(targetVersion)) {
+        throw new AgentOpsError("INVALID_TOOLKIT_VERSION", "Toolkit version must be a valid semantic version.");
+    }
     const report = await doctorInstallation({ root: options.root });
     for (const id of [
         "node-version",
@@ -108,7 +112,7 @@ export async function createUpdatePlan(options) {
         harness: options.harness ?? report.manifest.harness,
         profiles: configPreview.migrated.profiles,
         adapters: options.adapters,
-        toolkitVersion: targetVersion,
+        toolkitVersion: options.toolkitVersion ?? targetVersion,
         allowHarnessChange: true,
         ...(options.hookRuntimePath === undefined
             ? {}

package/dist/runtime/src/logging/local-log.js

@@ -83,6 +83,31 @@ function sanitizeEvent(value) {
             result: value.result
         };
     }
+    if (value.type === "loop-event") {
+        if (!hasExactKeys(value, ["code", "event", "outcome", "type"]) ||
+            typeof value.code !== "string" ||
+            !ID_PATTERN.test(value.code) ||
+            ![
+                "permission-request",
+                "post-compact",
+                "post-tool-use",
+                "pre-compact",
+                "pre-tool-use",
+                "session-start",
+                "subagent-start",
+                "subagent-stop",
+                "user-prompt-submit"
+            ].includes(String(value.event)) ||
+            !["allowed", "blocked", "observed"].includes(String(value.outcome))) {
+            return invalidEvent();
+        }
+        return {
+            type: "loop-event",
+            event: value.event,
+            outcome: value.outcome,
+            code: value.code
+        };
+    }
     return invalidEvent();
 }
 function serialize(stored) {

package/dist/runtime/src/schema/validate.js

@@ -2,7 +2,7 @@ import { CONFIG_SCHEMA_VERSION, EVIDENCE_SCHEMA_VERSION, MANIFEST_SCHEMA_VERSION
 const ID_PATTERN = /^[a-z][a-z0-9-]{0,127}$/;
 const HASH_PATTERN = /^[a-f0-9]{64}$/;
 const WINDOWS_RESERVED_SEGMENT = /^(?:aux|com[1-9]|con|lpt[1-9]|nul|prn)(?:\..*)?$/i;
-const PROFILE_VALUES = new Set(["advisory", "core", "guardrails"]);
+const PROFILE_VALUES = new Set(["advisory", "core", "guardrails", "loop"]);
 const EVIDENCE_KINDS = new Set(["exit-code", "file", "test-count"]);
 const SCOPE_VALUES = new Set(["project", "user"]);
 const HARNESS_VALUES = new Set(["claude", "codex", "opencode"]);
@@ -10,7 +10,14 @@ const HARNESS_VALUES = new Set(["claude", "codex", "opencode"]);
 const HOOK_HARNESS_VALUES = new Set(["claude", "codex"]);
 const HOOK_EVENT_VALUES = new Set([
     "SessionStart",
+    "UserPromptSubmit",
     "PreToolUse",
+    "PermissionRequest",
+    "PostToolUse",
+    "PreCompact",
+    "PostCompact",
+    "SubagentStart",
+    "SubagentStop",
     "Stop"
 ]);
 const MAX_TIMEOUT_MS = 2_147_483_647;

package/docs/en/guides/configuration.md

@@ -23,12 +23,83 @@ 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 settings require that explicit target.
+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:
@@ -58,7 +129,12 @@ agent-ops update
 agent-ops trust grant
 ```
 
-Without `update`, doctor reports `UPDATE_REQUIRED`; without the new trust
+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

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

@@ -2,8 +2,11 @@
 
 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. Revalidate:
-when either vendor reference changes.
+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
 
@@ -42,18 +45,19 @@ capabilities and MUST track generated source as one whole-file artifact.
 
 The opencode shim MUST invoke the absolute runtime path from the selected
 project directory, MUST fail open for
-advisory events, and MUST fail closed for command-policy events when the
+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 the 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.
+  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;
-  doctor reports OpenCode lifecycle support as `DEGRADED`.
-- Positive: `A missing runtime does not block SessionStart but blocks a bash tool before execution.`
-- Negative: `Fall back to a PATH-resolved agent-ops executable or claim app initialization is a per-session Stop-equivalent.`
+  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
 
@@ -67,11 +71,31 @@ decoding, normalized events, native output encoding, and runtime-failure output.
   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, and unsupported Stop/lifecycle registrations are not
-  reported as enforcement success.
-- Positive: `Claude command-policy reaches a native PreToolUse denial through runHookCommand.`
+  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 |
@@ -80,6 +104,20 @@ The current registration matrix is intentionally asymmetric:
 | 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.