@kylecheng3146/agent-ops 0.1.19 → 0.1.21

package/dist/runtime/src/hooks/completion-gate.js

@@ -0,0 +1,209 @@
+import { join } from "node:path";
+import { calculateConfigHash } from "../config/hash.js";
+import { sha256 } from "../fs/hash.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { findReviewAttestation } from "../review/attestation.js";
+import { validateEvidence, validateTaskAgainstConfig } from "../schema/validate.js";
+import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
+import { isPassingVerificationEvidence } from "../verify/evidence.js";
+import { collectChangeSurface } from "../verify/change-surface.js";
+import { calculateSourceFingerprint } from "../verify/source-fingerprint.js";
+const FINGERPRINT = /^[a-f0-9]{64}$/u;
+const SESSION = /^[^\0\r\n]{1,256}$/u;
+function gateResult(action, status, code, remedy) {
+    return { action, status, code, ...(remedy === undefined ? {} : { remedy }) };
+}
+function statePath(root, sessionId) {
+    return join(root, ".agent-ops", "tasks", "completion-gate", `${sha256(sessionId)}.json`);
+}
+function parseState(source, sessionId) {
+    if (source === null)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch {
+        throw new AgentOpsError("COMPLETION_GATE_STATE_INVALID", "Completion-gate state is not valid JSON.");
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new AgentOpsError("COMPLETION_GATE_STATE_INVALID", "Completion-gate state is invalid.");
+    }
+    const record = value;
+    if (Object.keys(record).sort().join(",") !==
+        "baselineFingerprint,permitFingerprint,schemaVersion,sessionId" ||
+        record.schemaVersion !== 1 ||
+        record.sessionId !== sessionId ||
+        typeof record.baselineFingerprint !== "string" ||
+        !FINGERPRINT.test(record.baselineFingerprint) ||
+        (record.permitFingerprint !== null &&
+            (typeof record.permitFingerprint !== "string" ||
+                !FINGERPRINT.test(record.permitFingerprint)))) {
+        throw new AgentOpsError("COMPLETION_GATE_STATE_INVALID", "Completion-gate state is invalid.");
+    }
+    return record;
+}
+export class FileCompletionGateStore {
+    #root;
+    constructor(root) {
+        this.#root = root;
+    }
+    async read(sessionId) {
+        if (!SESSION.test(sessionId)) {
+            throw new AgentOpsError("COMPLETION_GATE_SESSION_INVALID", "Completion gate requires a valid session identity.");
+        }
+        const path = statePath(this.#root, sessionId);
+        return await withPrivateFileLock(path, this.#root, async () => parseState(await readPrivateFile(path, this.#root), sessionId));
+    }
+    async mutate(sessionId, action) {
+        if (!SESSION.test(sessionId)) {
+            throw new AgentOpsError("COMPLETION_GATE_SESSION_INVALID", "Completion gate requires a valid session identity.");
+        }
+        const path = statePath(this.#root, sessionId);
+        return await withPrivateFileLock(path, this.#root, async () => {
+            const next = action(parseState(await readPrivateFile(path, this.#root), sessionId));
+            parseState(JSON.stringify(next), sessionId);
+            await writePrivateFile(path, `${JSON.stringify(next, null, 2)}\n`, this.#root);
+            return next;
+        });
+    }
+}
+export class CompletionGateService {
+    #options;
+    #store;
+    constructor(options) {
+        this.#options = options;
+        this.#store = options.stateStore ?? new FileCompletionGateStore(options.root);
+    }
+    async #fingerprint() {
+        const surface = await collectChangeSurface(this.#options.gitRunner);
+        return await calculateSourceFingerprint(this.#options.root, { mode: "worktree", changedFiles: surface.paths }, this.#options.gitRunner);
+    }
+    async initialize(sessionId) {
+        const fingerprint = await this.#fingerprint();
+        const state = await this.#store.mutate(sessionId, (current) => current ?? {
+            schemaVersion: 1,
+            sessionId,
+            baselineFingerprint: fingerprint,
+            permitFingerprint: null
+        });
+        const changed = state.baselineFingerprint !== fingerprint;
+        return gateResult("continue", changed ? "UNKNOWN" : "PASS", changed ? "COMPLETION_GATE_CHANGED" : "COMPLETION_GATE_READY", changed
+            ? `Git-visible changes require an attached completed task, current PASS evidence, and a PASS review. Session: ${sessionId}. Create with --session ${sessionId}; one-time permit: agent-ops allow-stop --session ${sessionId}.`
+            : undefined);
+    }
+    async grantPermit(sessionId) {
+        const fingerprint = await this.#fingerprint();
+        await this.#store.mutate(sessionId, (state) => {
+            if (state === null) {
+                throw new AgentOpsError("COMPLETION_GATE_NOT_INITIALIZED", "The session has no completion-gate baseline.");
+            }
+            return { ...state, permitFingerprint: fingerprint };
+        });
+    }
+    #isPermitCommand(event, sessionId) {
+        if (event.event !== "command")
+            return false;
+        const tokens = [event.command, ...event.args];
+        const commandIndex = tokens.indexOf("allow-stop");
+        return commandIndex >= 0 &&
+            tokens[commandIndex + 1] === "--session" &&
+            (tokens[commandIndex + 2] === sessionId ||
+                tokens[commandIndex + 2] === "$AGENT_OPS_SESSION_ID");
+    }
+    async #hasCurrentEvidence(taskId, criterionId, command, references, configHash, sourceFingerprint) {
+        for (const reference of references) {
+            if (reference.startsWith("review:"))
+                continue;
+            const validation = validateEvidence(await this.#options.evidenceStore.load(reference));
+            if (!validation.ok)
+                continue;
+            const evidence = validation.value;
+            if (evidence.taskId === taskId &&
+                evidence.criterionId === criterionId &&
+                evidence.commandId === command.id &&
+                evidence.configHash === configHash &&
+                evidence.sourceFingerprint === sourceFingerprint &&
+                isPassingVerificationEvidence(command, evidence)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    async #validateTask(sessionId, sourceFingerprint) {
+        let stored;
+        try {
+            stored = await this.#options.taskService.status({ sessionId });
+        }
+        catch (error) {
+            return error instanceof AgentOpsError && error.code === "TASK_SESSION_UNATTACHED"
+                ? gateResult("block", "FAIL", "COMPLETION_GATE_TASK_REQUIRED", "Attach this conversation to a formal task.")
+                : gateResult("block", "UNKNOWN", "COMPLETION_GATE_TASK_UNAVAILABLE", "Repair task state with agent-ops doctor before stopping.");
+        }
+        if (stored.status !== "complete") {
+            return gateResult("block", "FAIL", "COMPLETION_GATE_TASK_INCOMPLETE", "Complete the attached task after verification and review.");
+        }
+        const taskValidation = validateTaskAgainstConfig(stored.task, this.#options.config);
+        const configHash = calculateConfigHash(this.#options.config);
+        if (!taskValidation.ok || stored.policyConfigHash !== configHash) {
+            return gateResult("block", "FAIL", "COMPLETION_GATE_TASK_STALE", "Recreate or re-verify the task against the current config.");
+        }
+        for (const criterion of stored.task.criteria) {
+            for (const commandId of criterion.verifierIds) {
+                const command = this.#options.config.verification.commands.find(({ id }) => id === commandId);
+                if (command === undefined) {
+                    return gateResult("block", "UNKNOWN", "COMPLETION_GATE_EVIDENCE_UNAVAILABLE", "Configured task evidence cannot be resolved.");
+                }
+                if (command.required &&
+                    !(await this.#hasCurrentEvidence(stored.task.id, criterion.id, command, stored.evidence[criterion.id] ?? [], configHash, sourceFingerprint))) {
+                    return gateResult("block", "FAIL", "COMPLETION_GATE_EVIDENCE_REQUIRED", "Run agent-ops verify and complete the task with current PASS evidence.");
+                }
+            }
+        }
+        const attestation = await findReviewAttestation(this.#options.root, sourceFingerprint);
+        if (attestation === null || attestation.taskId !== stored.task.id) {
+            return gateResult("block", "FAIL", "COMPLETION_GATE_REVIEW_REQUIRED", "Run agent-ops review --yes for the attached task and current source.");
+        }
+        return null;
+    }
+    async handle(event) {
+        const sessionId = event.sessionId;
+        if (sessionId === undefined) {
+            return event.event === "stop"
+                ? gateResult("block", "UNKNOWN", "COMPLETION_GATE_SESSION_REQUIRED", "Agy did not provide conversationId; run doctor and use a one-time permit only after restoring hook input.")
+                : null;
+        }
+        if (event.event === "session-start") {
+            return await this.initialize(sessionId);
+        }
+        if (this.#isPermitCommand(event, sessionId)) {
+            return gateResult("block", "UNKNOWN", "COMPLETION_GATE_PERMIT_CONFIRMATION", "Allow this command only to grant one Stop for the current source fingerprint.");
+        }
+        if (event.event !== "stop")
+            return null;
+        if (event.terminationReason !== "model_stop" || event.fullyIdle !== true) {
+            return gateResult("continue", "PASS", "COMPLETION_GATE_NON_FINAL_STOP");
+        }
+        const fingerprint = await this.#fingerprint();
+        const state = await this.#store.read(sessionId);
+        if (state === null) {
+            return gateResult("block", "UNKNOWN", "COMPLETION_GATE_NOT_INITIALIZED", "The session baseline is unavailable; continue once so PreInvocation can initialize it.");
+        }
+        if (state.baselineFingerprint !== fingerprint && state.permitFingerprint !== fingerprint) {
+            const failure = await this.#validateTask(sessionId, fingerprint);
+            if (failure !== null)
+                return failure;
+        }
+        await this.#store.mutate(sessionId, (current) => {
+            if (current === null) {
+                throw new AgentOpsError("COMPLETION_GATE_NOT_INITIALIZED", "The session baseline disappeared.");
+            }
+            return {
+                ...current,
+                baselineFingerprint: fingerprint,
+                permitFingerprint: null
+            };
+        });
+        return gateResult("continue", "PASS", "COMPLETION_GATE_ALLOWED");
+    }
+}

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

@@ -35,6 +35,12 @@ function evaluateCommands(commands, scope) {
     return warning ?? continueWith("PASS", "GUARDRAIL_ALLOWED");
 }
 export async function dispatchHookEvent(event, options) {
+    if (options.completionGate !== undefined) {
+        const result = await options.completionGate.handle(event);
+        if (result !== null) {
+            return result;
+        }
+    }
     if (event.event === "unsupported") {
         return continueWith("UNKNOWN", "HOOK_EVENT_UNSUPPORTED");
     }

package/dist/runtime/src/install/codex-loop.js

@@ -134,12 +134,16 @@ export function planLoopContribution(options) {
         return { artifacts: [], blocks: [] };
     }
     const harnesses = selectedLoopHarnesses(options.harnesses);
-    if (options.scope !== "project" || harnesses.length === 0) {
-        throw new AgentOpsError("LOOP_PROFILE_UNSUPPORTED", "The loop profile requires project scope and the Codex or Claude harness.");
+    if (options.scope !== "project" ||
+        (harnesses.length === 0 && !options.harnesses.includes("agy"))) {
+        throw new AgentOpsError("LOOP_PROFILE_UNSUPPORTED", "The loop profile requires project scope and the agy, Codex, or Claude harness.");
     }
     if (options.hookRuntimePath === undefined) {
         throw new AgentOpsError("LOOP_RUNTIME_REQUIRED", "The loop profile requires the installed hook runtime path.");
     }
+    if (harnesses.length === 0) {
+        return { artifacts: [], blocks: [] };
+    }
     const artifacts = harnesses.flatMap((harness) => [
         {
             id: loopLauncherArtifactId(harness),

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

@@ -309,6 +309,16 @@ function checkLifecycleSummary(manifest, config) {
     }
     return check("lifecycle-summary", "PASS", "Lifecycle summary is reachable for every selected harness.");
 }
+function checkProjectLoop(manifest, config) {
+    if (manifest === undefined || config === undefined || !config.profiles.includes("loop")) {
+        return undefined;
+    }
+    return manifest.harness.includes("agy")
+        ? check("project-loop", "DEGRADED", config.features.completionGate.enabled
+            ? "agy completion gate uses PreInvocation, PreToolUse(run_command), and Stop; native Stop continuation is host-bounded. Use `agent-ops agy-run -- <args>` for a process-exit gate in headless or CI runs."
+            : "agy loop uses only PreInvocation and PreToolUse(run_command); prompt, permission, compact, and subagent events are unavailable.")
+        : check("project-loop", "PASS", "Project loop events are fully registered.");
+}
 async function checkSurfaceInventory(root, manifest, config) {
     if (manifest === undefined || config === undefined) {
         return {
@@ -420,6 +430,13 @@ export async function doctorInstallation(options) {
         await checkRegistrationDrift(options.root, manifest.manifest, config.config),
         await checkProbe("hook-registration", options.probes?.hookRegistration),
         checkLifecycleSummary(manifest.manifest, config.config),
+        ...(() => {
+            const projectLoop = checkProjectLoop(manifest.manifest, config.config);
+            return projectLoop === undefined ? [] : [projectLoop];
+        })(),
+        ...(manifest.manifest?.harness.includes("agy") === true
+            ? [await checkProbe("agy-runtime", options.probes?.agyRuntime)]
+            : []),
         await checkProbe("repository-trust", options.probes?.repositoryTrust),
         await checkProbe("smoke-availability", options.probes?.smokeAvailability),
         await checkReviewTargets(config.config, options.probes?.reviewTarget, options.checkReviewTargetAuth === true)

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

@@ -1,3 +1,8 @@
+import { buildAgyHookSettings, isAgyHookRegistered, isAgyManagedHook, mergeAgyHooks, stripAgyHooks } from "../adapters/agy/config.js";
+import { AGY_CAPABILITY_REGISTRATIONS } from "../adapters/agy/events.js";
+import { normalizeAgyHookInput } from "../adapters/agy/input.js";
+import { agyHookOutput } from "../adapters/agy/output.js";
+import { agySurfaces } from "../adapters/agy/surfaces.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";
@@ -16,6 +21,7 @@ import { opencodeSurfaces } from "../adapters/opencode/surfaces.js";
 import { AgentOpsError } from "../fs/paths.js";
 import { findSurfaceById, findSurfaceByPath, isWritableSurface } from "./surfaces.js";
 export const HARNESS_IDS = [
+    "agy",
     "codex",
     "claude",
     "opencode"
@@ -108,7 +114,52 @@ const CLAUDE_ROUTING = {
         "## Loop Engineering\n\nUse `.agent-ops/CLAUDE.md` as the canonical Loop Engineering specification for this project.\n"
     ]
 };
+const AGY_ROUTING = {
+    desired: "## Loop Engineering\n\nLoad `.agent-ops/GEMINI.md` as the agent-ops managed baseline.\nProject-specific instructions in this file remain authoritative.\n",
+    legacy: []
+};
 const DESCRIPTORS = {
+    agy: {
+        id: "agy",
+        control: {
+            instructionFile: "GEMINI.md",
+            routing: AGY_ROUTING,
+            hookPath: ".agents/hooks.json",
+            hookPathForScope: (scope) => scope === "project" ? ".agents/hooks.json" : ".gemini/config/hooks.json",
+            surfaces: agySurfaces,
+            ownSettingsKeys: [],
+            buildHooks: buildAgyHookSettings,
+            mergeHooks: mergeAgyHooks,
+            stripHooks: stripAgyHooks,
+            isManagedHandler: isAgyManagedHook,
+            registrations: AGY_CAPABILITY_REGISTRATIONS,
+            hookRegistered: (source, capabilities) => isAgyHookRegistered(parseJsonSource(source), capabilities),
+            plan: async (context) => {
+                if (context.scope === "project") {
+                    return await planCommonHarnessContribution("agy", context);
+                }
+                const descriptor = DESCRIPTORS.agy;
+                return {
+                    artifacts: [{
+                            id: "gemini-rules",
+                            path: ".agent-ops/GEMINI.md",
+                            content: managedRules(descriptor, context)
+                        }],
+                    blocks: [{
+                            id: "agy-routing",
+                            path: ".gemini/GEMINI.md",
+                            version: 1,
+                            content: AGY_ROUTING.desired
+                        }]
+                };
+            }
+        },
+        runtime: {
+            normalizeInput: normalizeAgyHookInput,
+            formatOutput: agyHookOutput,
+            formatRuntimeFailure: (event, capability, remedy) => agyHookOutput(event, runtimeFailureResult(capability, AGY_CAPABILITY_REGISTRATIONS, remedy))
+        }
+    },
     codex: createJsonDescriptor({
         id: "codex",
         instructionFile: "AGENTS.md",
@@ -230,6 +281,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;
+export const COMMON_GEMINI_BLOCK = DESCRIPTORS.agy.control.routing.desired;
 export function managedRules(descriptor, context) {
     const lines = [
         "# Loop Engineering",
@@ -244,7 +296,7 @@ export function managedRules(descriptor, context) {
         ""
     ];
     if (context.capabilities.includes("rules")) {
-        lines.push("For every change:", "", "1. Define two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope and preserve unrelated changes.", "3. Apply the smallest safe change.", "4. Run evidence-producing verification for every criterion.", "5. Obtain independent review before claiming completion, via", "   `agent-ops review --yes` (or the CLI's equivalent invocation). Never call a", "   review-target CLI (agy, codex, claude) directly — direct calls skip", "   the enforced read-only sandbox flags and can hang or fail on command", "   permission prompts.", "", "Treat `.agent-ops/config.json` as verifier authority. Discovery output is", "only a proposal until a user confirms it. Repository commands require an", "exact matching trust record. Confirmed project init/update grants it", "automatically when verification commands are configured.", "");
+        lines.push("For every change:", "", "1. Define two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope and preserve unrelated changes.", "3. Apply the smallest safe change.", "4. Run evidence-producing verification for every criterion.", "5. Obtain independent review before claiming completion, via", "   `agent-ops review --yes` (or the CLI's equivalent invocation). Never call a", "   review-target CLI (agy, codex, claude) directly — direct calls skip", "   the enforced read-only sandbox flags and can hang or fail on command", "   permission prompts.", "   Set `AGENT_OPS_HOST` to the current CLI id when invoking review so", "   agent-ops tries a different CLI first and uses isolated self-review", "   only when no other configured reviewer is usable.", "", "Treat `.agent-ops/config.json` as verifier authority. Discovery output is", "only a proposal until a user confirms it. Repository commands require an", "exact matching trust record. Confirmed project init/update grants it", "automatically when verification commands are configured.", "");
     }
     if (context.capabilities.includes("task")) {
         lines.push("Split a change that exceeds five acceptance criteria into subtasks:", "`agent-ops task create --parent <task-id>` records one, and", "`agent-ops task status --parent <task-id>` lists them. Each subtask", "carries its own criteria, verification, and independent review;", "completing one never completes its parent.", "");
@@ -255,6 +307,9 @@ export function managedRules(descriptor, context) {
     if (context.capabilities.includes("command-policy")) {
         lines.push("Command policy guards high-confidence unsafe actions. Explicitly enabled", "Stop verification is report-only and never marks a task complete by itself.", "");
     }
+    if (context.capabilities.includes("completion-gate")) {
+        lines.push("The agy completion gate applies only when this conversation creates a", "Git-visible net change after its first PreInvocation baseline. Read-only", "questions and analysis stop normally. A changed conversation must be", "attached to one task with two to five acceptance criteria; current PASS", "verification evidence, a PASS review attestation, and completed task state", "are all required before Stop. Error, max-step, and non-idle stops are not", "blocked. The gate inspects evidence but never runs tests or review itself.", "A user may approve `agent-ops allow-stop --session <conversationId>` for", "one Stop bound to the current source fingerprint; the PreToolUse hook must", "return `force_ask`, so the agent cannot self-authorize this escape hatch.", "For headless or CI enforcement, launch agy through", "`agent-ops agy-run -- <agy arguments>`.", "");
+    }
     lines.push(`This file is routed from the active ${descriptor.control.instructionFile}.`, "");
     return lines.join("\n");
 }

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

@@ -35,7 +35,9 @@ export function planHookRegistration(options) {
     }
     const path = options.path ?? hookRegistrationPath(options.harness, options.scope);
     const managed = descriptor.control.buildHooks(options.capabilities, options.runtimePath, options.platform);
-    const events = Object.keys(managed.hooks);
+    const events = Object.keys(managed.hooks).map((event) => options.harness === "agy" && event === "PreInvocation"
+        ? "SessionStart"
+        : event);
     if (events.length === 0) {
         return null;
     }
@@ -54,6 +56,9 @@ export function planHookRegistration(options) {
     };
 }
 function onlyManagedRemains(harness, value) {
+    if (harness === "agy") {
+        return Object.keys(value).length === 0;
+    }
     const ownKeys = new Set(harnessDescriptor(harness).control.ownSettingsKeys ?? []);
     const hooks = value.hooks;
     return (Object.keys(value).every((key) => ownKeys.has(key)) &&

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

@@ -4,13 +4,15 @@ import { harnessDescriptor, harnessHookPath, routingBlockId, selectHarnessHookSu
 import { isOpencodePluginPath } from "../adapters/opencode/config.js";
 import { LOOP_MARKER_ID, LOOP_MARKER_VERSION, loopIgnoreContent, loopLauncherArtifactId, loopWindowsLauncherArtifactId, loopWindowsLauncherPath, loopLauncherPath, selectedLoopHarnesses } from "./codex-loop.js";
 function expectedMarker(manifest, id, markerId) {
-    const descriptor = harnessDescriptor(id);
+    const descriptor = manifestDescriptor(manifest, id);
     const markers = managedBlockMarkers(markerId, 1, "html");
     return {
         id: markerId,
         path: manifest.scope === "project"
             ? descriptor.control.instructionFile
-            : `.${id}/${descriptor.control.instructionFile}`,
+            : id === "agy"
+                ? ".gemini/GEMINI.md"
+                : `.${id}/${descriptor.control.instructionFile}`,
         startMarker: markers.start,
         endMarker: markers.end,
         markerStyle: "html",
@@ -18,6 +20,13 @@ function expectedMarker(manifest, id, markerId) {
         legacyContent: descriptor.control.routing.legacy
     };
 }
+function manifestDescriptor(manifest, id) {
+    const legacyProjectAgy = id === "agy" &&
+        manifest.scope === "project" &&
+        !manifest.artifacts.some(({ path }) => path === ".agent-ops/GEMINI.md") &&
+        !manifest.markers.some(({ id: markerId }) => markerId === "agy-routing");
+    return harnessDescriptor(legacyProjectAgy ? "codex" : id);
+}
 function expectedLoopMarker(manifest) {
     const markers = managedBlockMarkers(LOOP_MARKER_ID, LOOP_MARKER_VERSION, "hash");
     return {
@@ -96,7 +105,7 @@ export function assertSupportedManifestOwnership(manifest, root) {
         throw manifestOwnershipError();
     }
     for (const id of harnesses) {
-        const descriptor = harnessDescriptor(id);
+        const descriptor = manifestDescriptor(manifest, id);
         const artifactPath = `.agent-ops/${descriptor.control.instructionFile}`;
         const artifactKey = pathKey(artifactPath);
         const artifactEntry = expectedArtifactPaths.get(artifactKey);
@@ -112,7 +121,9 @@ export function assertSupportedManifestOwnership(manifest, root) {
         requiredArtifactPaths.add(artifactKey);
         const markerPath = manifest.scope === "project"
             ? descriptor.control.instructionFile
-            : `.${id}/${descriptor.control.instructionFile}`;
+            : id === "agy"
+                ? ".gemini/GEMINI.md"
+                : `.${id}/${descriptor.control.instructionFile}`;
         const markerKey = pathKey(markerPath);
         expectedMarkerPaths.add(markerKey);
         const currentId = routingBlockId(id, manifest.scope, descriptor);

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

@@ -71,7 +71,7 @@ async function detectVerificationCommands(root) {
         .filter((proposal) => proposal.confidence === "high")
         .map(verificationCommandFromProposal);
 }
-function buildConfig(profiles, existing, reviewTargets = [], detectedCommands = []) {
+function buildConfig(profiles, existing, reviewTargets = [], detectedCommands = [], completionGateEnabled = false) {
     // Absent reviewRoles means external review is disabled; an empty selection
     // must therefore omit the field rather than write an empty array.
     const reviewRoles = reviewTargets.length > 0
@@ -88,6 +88,9 @@ function buildConfig(profiles, existing, reviewTargets = [], detectedCommands =
         features: existing?.features ?? {
             stopVerification: {
                 enabled: false
+            },
+            completionGate: {
+                enabled: completionGateEnabled
             }
         },
         pathMappings: existing?.pathMappings ?? [],
@@ -95,7 +98,7 @@ function buildConfig(profiles, existing, reviewTargets = [], detectedCommands =
         ...(reviewRoles === undefined ? {} : { reviewRoles: [...reviewRoles] })
     };
 }
-async function planConfig(root, profiles, existingManifest, suppliedConfig, reviewTargets = []) {
+async function planConfig(root, profiles, existingManifest, suppliedConfig, reviewTargets = [], completionGateEnabled = false) {
     const current = await readCurrentFile(root, CONFIG_PATH);
     const owned = findOwnedArtifact(existingManifest, CONFIG_PATH);
     if (current !== null && owned === undefined) {
@@ -131,7 +134,7 @@ async function planConfig(root, profiles, existingManifest, suppliedConfig, revi
         existingConfig.verification.commands.length === 0
         ? await detectVerificationCommands(root)
         : [];
-    const config = buildConfig(profiles, existingConfig, reviewTargets, detectedCommands);
+    const config = buildConfig(profiles, existingConfig, reviewTargets, detectedCommands, completionGateEnabled);
     const content = `${JSON.stringify(config, null, 2)}\n`;
     return {
         operation: {
@@ -280,8 +283,8 @@ function assertLoopProfileSupport(scope, harness, capabilities) {
         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.");
+        !harness.some((id) => id === "agy" || id === "codex" || id === "claude")) {
+        throw new AgentOpsError("LOOP_PROFILE_UNSUPPORTED", "The loop profile requires project scope and the agy, Codex, or Claude harness.");
     }
 }
 async function assertCodexLoopConfiguration(root, harness, capabilities) {
@@ -376,6 +379,18 @@ export async function createInstallPlan(options) {
         ? resolveProfiles(options.profiles)
         : resolveCapabilities(options.existingConfig.value);
     assertLoopProfileSupport(options.scope, options.harness, resolved.capabilities);
+    const completionGateEnabled = options.existingConfig?.value.features.completionGate.enabled ??
+        options.completionGateEnabled === true;
+    if (completionGateEnabled &&
+        (options.scope !== "project" ||
+            !options.harness.includes("agy") ||
+            !resolved.capabilities.includes("project-loop"))) {
+        throw new AgentOpsError("COMPLETION_GATE_UNSUPPORTED", "The completion gate requires project scope with the agy harness and loop profile.");
+    }
+    if (completionGateEnabled &&
+        !resolved.capabilities.includes("completion-gate")) {
+        resolved.capabilities.push("completion-gate");
+    }
     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);
@@ -461,7 +476,7 @@ export async function createInstallPlan(options) {
         : [];
     const operations = [];
     const artifacts = [];
-    const config = await planConfig(options.root, resolved.profiles, existing?.manifest ?? null, options.existingConfig, options.reviewTargets ?? []);
+    const config = await planConfig(options.root, resolved.profiles, existing?.manifest ?? null, options.existingConfig, options.reviewTargets ?? [], completionGateEnabled);
     operations.push(config.operation);
     artifacts.push(config.record);
     for (const artifact of contribution.artifacts) {

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

@@ -1,5 +1,66 @@
 import { harnessDescriptor } from "./harness.js";
 import { resolveCapabilities } from "./profiles.js";
+const MINIMUM_AGY_VERSION = [1, 1, 12];
+export function agyVersionSupported(versionOutput) {
+    const match = /\b(\d+)\.(\d+)\.(\d+)\b/u.exec(versionOutput);
+    const version = match?.slice(1).map(Number);
+    return version !== undefined && !version.some((part, index) => part < MINIMUM_AGY_VERSION[index] &&
+        version.slice(0, index).every((prior, priorIndex) => prior === MINIMUM_AGY_VERSION[priorIndex]));
+}
+export function agyRuntimeStatus(versionOutput, hooksOutput, expectedEvents = []) {
+    const match = /\b(\d+)\.(\d+)\.(\d+)\b/u.exec(versionOutput);
+    if (!agyVersionSupported(versionOutput)) {
+        return {
+            status: "FAIL",
+            message: "agy 1.1.12 or newer is required.",
+            remediation: "Update agy, then run `agent-ops doctor` again."
+        };
+    }
+    try {
+        const parsed = JSON.parse(hooksOutput);
+        const hooks = parsed.command?.data?.hooks;
+        const loaded = Array.isArray(hooks) && hooks.some((hook) => {
+            if (typeof hook !== "object" || hook === null || Array.isArray(hook))
+                return false;
+            const value = hook;
+            const actions = value.actions;
+            if (!(value.name === "agent-ops" &&
+                value.enabled === true &&
+                Array.isArray(actions) &&
+                actions.length > 0 &&
+                actions.every((action) => typeof action === "object" && action !== null && !Array.isArray(action))))
+                return false;
+            return expectedEvents.every((expected) => actions.some((action) => {
+                const nativeEvent = expected === "SessionStart" ? "PreInvocation" : expected;
+                return (typeof action === "object" && action !== null && !Array.isArray(action) &&
+                    action.event === nativeEvent &&
+                    typeof action.command === "string" &&
+                    action.command.endsWith(` agy ${expected} --managed-by=agent-ops`));
+            }));
+        });
+        if (!Array.isArray(hooks) || (expectedEvents.length > 0 && !loaded)) {
+            return {
+                status: "FAIL",
+                message: "agy is installed, but its loaded hook list does not include agent-ops.",
+                code: "UPDATE_REQUIRED",
+                remediation: "Run `agent-ops update`, restart agy, then run doctor again."
+            };
+        }
+        return {
+            status: "PASS",
+            message: expectedEvents.length > 0
+                ? `agy ${match?.[0]} loaded the agent-ops hook.`
+                : `agy ${match?.[0]} meets the minimum supported version.`
+        };
+    }
+    catch {
+        return {
+            status: "FAIL",
+            message: "agy returned an unreadable /hooks response.",
+            remediation: "Run `agy -p \"/hooks\" --output-format json` and inspect the result."
+        };
+    }
+}
 /**
  * Returns the harness ids missing an agent-ops owned handler for the hook
  * events implied by the installed profiles. Empty when installations without

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

@@ -33,5 +33,8 @@ export function resolveCapabilities(config) {
     if (config.features.stopVerification.enabled) {
         resolved.capabilities.push("optional-stop-verify");
     }
+    if (config.features.completionGate.enabled) {
+        resolved.capabilities.push("completion-gate");
+    }
     return resolved;
 }

package/dist/runtime/src/install/surface-inspection.js

@@ -90,6 +90,9 @@ function managedJsonCount(source, isManagedHandler) {
     }
     return jsonHandlerCounts(source, isManagedHandler)?.managed ?? 0;
 }
+function desiredHookEvents(harness, events) {
+    return events.map((event) => harness === "agy" && event === "PreInvocation" ? "SessionStart" : event);
+}
 export async function inspectHarnessRegistrations(options) {
     const capabilities = desiredCapabilities(options.config);
     const statuses = [];
@@ -100,7 +103,7 @@ export async function inspectHarnessRegistrations(options) {
         const recordedEvents = hookRecord?.events ?? [];
         const desiredEvents = control.buildHooks === undefined
             ? []
-            : Object.keys(control.buildHooks(capabilities, "probe").hooks);
+            : desiredHookEvents(harness, Object.keys(control.buildHooks(capabilities, "probe").hooks));
         if (control.buildHooks !== undefined) {
             const surfaces = harnessSurfaces(harness, options.manifest.scope, options.root);
             const writableJsonSurfaces = surfaces.filter((surface) => isWritableSurface(surface) && surface.representation === "json");
@@ -186,6 +189,12 @@ function jsonHandlerCounts(source, isManagedHandler) {
     if (!isRecord(parsed)) {
         return null;
     }
+    if (isManagedHandler?.(parsed) === true) {
+        return {
+            managed: 1,
+            foreign: Math.max(0, Object.keys(parsed).length - 1)
+        };
+    }
     const hooks = parsed.hooks;
     if (hooks === undefined) {
         return { managed: 0, foreign: 0 };