@kylecheng3146/agent-ops 0.1.20 → 0.1.22

package/dist/packages/cli/src/hook-process.js

@@ -9,6 +9,10 @@ import { resolveContainedPath } from "../../../runtime/src/fs/paths.js";
 import { redactSecrets } from "../../../runtime/src/security/redact.js";
 import { claudeStopRecursionMarker } from "../../../runtime/src/adapters/claude/input.js";
 import { HARNESS_IDS, harnessDescriptor } from "../../../runtime/src/install/harness.js";
+import { CompletionGateService } from "../../../runtime/src/hooks/completion-gate.js";
+import { TaskService } from "../../../runtime/src/task/service.js";
+import { FileTaskStore } from "../../../runtime/src/task/store.js";
+import { FileEvidenceStore } from "../../../runtime/src/verify/evidence.js";
 import { STOP_VERIFICATION_ENV, StopVerificationService } from "../../../runtime/src/hooks/stop-service.js";
 import { NodeVerificationProcessRunner } from "../../../runtime/src/verify/spawn.js";
 import { normalizeHookInput, runHookCommand, HOOK_EVENTS } from "./commands/hook.js";
@@ -40,6 +44,16 @@ function parseInput(source) {
         return null;
     }
 }
+function withInjectedSession(harness, input) {
+    const sessionId = process.env.AGENT_OPS_SESSION_ID;
+    return harness === "agy" &&
+        sessionId !== undefined &&
+        typeof input === "object" &&
+        input !== null &&
+        !Array.isArray(input)
+        ? { ...input, conversationId: sessionId }
+        : input;
+}
 function writeHookOutput(io, output) {
     if (output.stdout.length > 0) {
         io.writeStdout(output.stdout);
@@ -195,11 +209,14 @@ function shouldBuildStopVerification(harness, event, config, rawInput) {
     return harnessDescriptor(harness).control.registrations.some(({ capability, support }) => capability === "optional-stop-verify" && support !== "unsupported");
 }
 /**
- * Runs one hook invocation. Always resolves to exit code 0: a hook that
- * cannot answer must never block the harness it advises.
+ * Runs one hook invocation. Exit code stays zero because native JSON carries
+ * decisions; only an explicitly installed agy completion gate fails closed.
  */
 export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
     const [harness, event] = argv;
+    const completionGateInstalled = harness === "agy" &&
+        event === "Stop" &&
+        argv.includes("--completion-gate");
     if (harness === undefined ||
         !HARNESSES.has(harness) ||
         event === undefined ||
@@ -212,13 +229,31 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
         const harnessId = harness;
         const hookEvent = event;
         if (process.env.AGENT_OPS_DISABLE === "1") {
+            if (completionGateInstalled) {
+                writeHookOutput(io, harnessDescriptor("agy").runtime.formatOutput("Stop", {
+                    action: "block",
+                    status: "UNKNOWN",
+                    code: "COMPLETION_GATE_DISABLE_REJECTED",
+                    remedy: "Use a user-approved one-time permit instead of disabling agent-ops."
+                }));
+                return 0;
+            }
             writeHookOutput(io, failOpenOutput(harnessId, hookEvent));
             return 0;
         }
         const rawInput = await readStdin(io.stdin);
-        const parsedInput = parseInput(rawInput);
+        const parsedInput = withInjectedSession(harnessId, parseInput(rawInput));
         const configOutcome = await hookConfigOutcome(root, dependencies.loadConfig);
         if (configOutcome.kind === "invalid") {
+            if (completionGateInstalled) {
+                writeHookOutput(io, harnessDescriptor("agy").runtime.formatOutput("Stop", {
+                    action: "block",
+                    status: "UNKNOWN",
+                    code: "COMPLETION_GATE_CONFIG_INVALID",
+                    remedy: `Fix ${redactSecrets(configOutcome.path)} and run agent-ops doctor.`
+                }));
+                return 0;
+            }
             const output = await invalidConfigOutput({
                 root,
                 harness: harnessId,
@@ -249,6 +284,17 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
                 processRunner
             })
             : undefined;
+        const completionGate = harnessId === "agy" && config.features.completionGate.enabled
+            ? dependencies.completionGate ?? {
+                handle: async (normalized) => await new CompletionGateService({
+                    root,
+                    config,
+                    gitRunner,
+                    taskService: new TaskService(new FileTaskStore(join(root, ".agent-ops", "tasks", "state.json"), root)),
+                    evidenceStore: new FileEvidenceStore(root, root)
+                }).handle(normalized)
+            }
+            : undefined;
         const output = await runHookCommand({
             harness: harness,
             event: hookEvent,
@@ -258,12 +304,20 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
             ...(dependencies.advisory === undefined
                 ? {}
                 : { advisory: dependencies.advisory }),
-            ...(stopVerification === undefined ? {} : { stopVerification })
+            ...(stopVerification === undefined ? {} : { stopVerification }),
+            ...(completionGate === undefined ? {} : { completionGate })
         });
         writeHookOutput(io, output);
     }
     catch {
-        // ponytail: fail-open by design; hook failures stay invisible to the harness.
+        if (completionGateInstalled) {
+            writeHookOutput(io, harnessDescriptor("agy").runtime.formatOutput("Stop", {
+                action: "block",
+                status: "UNKNOWN",
+                code: "COMPLETION_GATE_UNAVAILABLE",
+                remedy: "Run agent-ops doctor; use a user-approved one-time permit only after diagnosis."
+            }));
+        }
     }
     return 0;
 }

package/dist/packages/cli/src/wizard.js

@@ -34,6 +34,11 @@ function selectReviewTargets(raw, defaults = []) {
 function affirmative(raw) {
     return /^(y|yes)$/i.test(raw.trim());
 }
+function completionGateEligible(scope, harness, profiles) {
+    return scope === "project" &&
+        harness.includes("agy") &&
+        profiles.includes("loop");
+}
 async function probeReviewTargets(targets, setup) {
     const probe = setup.probeReviewTarget;
     if (probe === undefined) {
@@ -161,6 +166,20 @@ export async function completeInitChoices(args, io, setup = {}) {
                 selectAllLabel: "Select all",
                 selectAllDescription: "Enable core, advisory, guardrails, and loop together."
             });
+        const completionGate = args.completionGate ?? (completionGateEligible(scope, harness, profiles)
+            ? await selectOption("Enable the agy completion gate?", [
+                {
+                    label: "yes",
+                    value: true,
+                    description: "Recommended. Blocks changed sessions until task evidence and review pass."
+                },
+                {
+                    label: "no",
+                    value: false,
+                    description: "Keep advisory loop behavior."
+                }
+            ], selectorIo)
+            : false);
         const enabled = args.reviewTargets !== undefined ||
             (await selectOption("External review: call another agent CLI to review your work?", [
                 { label: "no", value: false, description: "Default. Nothing is spawned." },
@@ -180,6 +199,7 @@ export async function completeInitChoices(args, io, setup = {}) {
             scope,
             harness,
             profiles,
+            ...(completionGate ? { completionGate: true } : {}),
             ...(reviewTargets.length === 0 ? {} : { reviewTargets })
         };
     }
@@ -192,6 +212,9 @@ export async function completeInitChoices(args, io, setup = {}) {
         const profiles = args.profiles.length > 0
             ? args.profiles
             : selectProfiles(await session.question("Profiles (core,advisory,guardrails,loop) [core]: "));
+        const completionGate = args.completionGate ?? (completionGateEligible(scope, harness, profiles)
+            ? !/^(n|no)$/i.test((await session.question("Enable the recommended agy completion gate? [Y/n]: ")).trim())
+            : false);
         const defaultReviewTargets = REVIEW_TARGET_ORDER.filter((target) => harness.includes(target));
         const reviewTargets = args.reviewTargets ?? (affirmative(await session.question("Enable external review by another agent CLI? [y/N]: "))
             ? selectReviewTargets(await session.question(`Review targets (${defaultReviewTargets.join(",") || "none"}): `), defaultReviewTargets)
@@ -202,6 +225,7 @@ export async function completeInitChoices(args, io, setup = {}) {
             scope,
             harness,
             profiles,
+            ...(completionGate ? { completionGate: true } : {}),
             ...(reviewTargets.length === 0 ? {} : { reviewTargets })
         };
     }

package/dist/runtime/src/adapters/agy/config.js

@@ -5,10 +5,11 @@ function record(value) {
         ? value
         : null;
 }
-function handler(runtimePath, event, platform) {
+function handler(runtimePath, event, platform, completionGate = false) {
+    const gateFlag = completionGate ? " --completion-gate" : "";
     const command = platform === "win32"
-        ? `cmd /c node ${JSON.stringify(runtimePath).replaceAll("\\\\", "\\")} agy ${event} ${MARKER}`
-        : `node ${JSON.stringify(runtimePath)} agy ${event} ${MARKER}`;
+        ? `cmd /c node ${JSON.stringify(runtimePath).replaceAll("\\\\", "\\")} agy ${event}${gateFlag} ${MARKER}`
+        : `node ${JSON.stringify(runtimePath)} agy ${event}${gateFlag} ${MARKER}`;
     return {
         type: "command",
         command,
@@ -27,7 +28,9 @@ function managedHandler(value, event) {
         typeof candidate.command === "string" &&
         (candidate.command.startsWith("node \"") ||
             candidate.command.startsWith("cmd /c node \"")) &&
-        candidate.command.endsWith(` agy ${event} ${MARKER}`);
+        (candidate.command.endsWith(` agy ${event} ${MARKER}`) ||
+            (event === "Stop" &&
+                candidate.command.endsWith(` agy Stop --completion-gate ${MARKER}`)));
 }
 function managedEvent(value, event) {
     if (!Array.isArray(value) || value.length !== 1)
@@ -57,8 +60,9 @@ export function buildAgyHookSettings(capabilities, runtimePath, platform = proce
     if (capabilities.includes("command-policy") || capabilities.includes("project-loop")) {
         hooks.PreToolUse = [{ matcher: "run_command", hooks: [handler(runtimePath, "PreToolUse", platform)] }];
     }
-    if (capabilities.includes("optional-stop-verify")) {
-        hooks.Stop = [handler(runtimePath, "Stop", platform)];
+    if (capabilities.includes("optional-stop-verify") ||
+        capabilities.includes("completion-gate")) {
+        hooks.Stop = [handler(runtimePath, "Stop", platform, capabilities.includes("completion-gate"))];
     }
     return { hooks };
 }
@@ -79,8 +83,14 @@ export function isAgyHookRegistered(value, capabilities) {
     const named = record(record(value)?.["agent-ops"]);
     if (named === null || !isAgyManagedHook(value))
         return false;
-    return Object.keys(expected)
+    const eventsMatch = Object.keys(expected)
         .every((event) => managedEvent(named[event], event));
+    if (!eventsMatch || !capabilities.includes("completion-gate")) {
+        return eventsMatch;
+    }
+    const stop = Array.isArray(named.Stop) ? record(named.Stop[0]) : null;
+    return typeof stop?.command === "string" &&
+        stop.command.endsWith(` agy Stop --completion-gate ${MARKER}`);
 }
 export function mergeAgyHooks(existing, managed) {
     const source = record(existing);

package/dist/runtime/src/adapters/agy/events.js

@@ -16,6 +16,14 @@ export const AGY_CAPABILITY_REGISTRATIONS = [
         support: "supported",
         runtimeFailure: "fail-closed"
     },
+    {
+        capability: "completion-gate",
+        normalizedEvent: "stop",
+        nativeEvent: "Stop",
+        surfaceId: "agy-hooks",
+        support: "supported",
+        runtimeFailure: "fail-closed"
+    },
     {
         capability: "optional-stop-verify",
         normalizedEvent: "stop",

package/dist/runtime/src/adapters/agy/input.js

@@ -15,16 +15,34 @@ export function normalizeAgyHookInput(input) {
     const projectRoot = typeof workspacePaths[0] === "string"
         ? workspacePaths[0]
         : undefined;
+    const sessionId = typeof value.conversationId === "string"
+        ? value.conversationId
+        : undefined;
     const toolCall = record(value.toolCall);
     const args = record(toolCall?.args);
     if (toolCall?.name === "run_command" && typeof args?.CommandLine === "string") {
-        return normalizeShellHookEvent(args.CommandLine, projectRoot);
+        return {
+            ...normalizeShellHookEvent(args.CommandLine, projectRoot),
+            ...(sessionId === undefined ? {} : { sessionId })
+        };
     }
     if (typeof value.terminationReason === "string") {
-        return normalizeHookEvent({ event: "stop", projectRoot });
+        return {
+            event: "stop",
+            projectRoot: projectRoot ?? process.cwd(),
+            ...(sessionId === undefined ? {} : { sessionId }),
+            terminationReason: value.terminationReason,
+            ...(typeof value.fullyIdle === "boolean"
+                ? { fullyIdle: value.fullyIdle }
+                : {})
+        };
     }
     if (typeof value.invocationNum === "number") {
-        return normalizeHookEvent({ event: "session-start", projectRoot });
+        return {
+            event: "session-start",
+            projectRoot: projectRoot ?? process.cwd(),
+            ...(sessionId === undefined ? {} : { sessionId })
+        };
     }
     return normalizeHookEvent({ event: "unsupported", projectRoot });
 }

package/dist/runtime/src/adapters/agy/output.js

@@ -12,13 +12,17 @@ export function agyHookOutput(event, result) {
         ? `agent-ops: ${result.code}`
         : `agent-ops: ${result.code}: ${result.remedy}`;
     const value = event === "PreToolUse"
-        ? result.action === "block"
-            ? { decision: "deny", reason }
-            : { decision: "allow" }
+        ? result.code === "COMPLETION_GATE_PERMIT_CONFIRMATION"
+            ? { decision: "force_ask", reason }
+            : result.action === "block"
+                ? { decision: "deny", reason }
+                : { decision: "allow" }
         : event === "SessionStart"
             ? { injectSteps: [{ ephemeralMessage: reason }] }
             : event === "Stop"
-                ? { decision: "allow", reason }
+                ? result.action === "block" && result.code.startsWith("COMPLETION_GATE_")
+                    ? { decision: "continue", reason }
+                    : { decision: "allow", reason }
                 : {};
     return { exitCode: 0, stdout: JSON.stringify(value), stderr: "" };
 }

package/dist/runtime/src/config/explain.js

@@ -2,6 +2,11 @@ export function explainConfig(merged) {
     return {
         schemaVersion: merged.config.schemaVersion,
         features: {
+            completionGate: {
+                enabled: merged.config.features.completionGate.enabled,
+                source: merged.provenance.features.source,
+                sourcePath: merged.provenance.features.sourcePath
+            },
             stopVerification: {
                 enabled: merged.config.features.stopVerification.enabled,
                 source: merged.provenance.features.source,

package/dist/runtime/src/config/migrate.js

@@ -25,7 +25,7 @@ const MIGRATIONS = new Map([
             const { schemaVersion: _schemaVersion, ...rest } = input;
             return {
                 ...rest,
-                schemaVersion: CONFIG_SCHEMA_VERSION,
+                schemaVersion: 2,
                 features: {
                     stopVerification: {
                         enabled: false
@@ -33,6 +33,20 @@ const MIGRATIONS = new Map([
                 }
             };
         }
+    ],
+    [
+        2,
+        (input) => {
+            const { schemaVersion: _schemaVersion, features, ...rest } = input;
+            return {
+                ...rest,
+                schemaVersion: CONFIG_SCHEMA_VERSION,
+                features: {
+                    ...(isRecord(features) ? features : {}),
+                    completionGate: { enabled: false }
+                }
+            };
+        }
     ]
 ]);
 function schemaVersionOf(value) {

package/dist/runtime/src/contracts.js

@@ -1,4 +1,4 @@
-export const CONFIG_SCHEMA_VERSION = 2;
+export const CONFIG_SCHEMA_VERSION = 3;
 export const TASK_SCHEMA_VERSION = 1;
 export const EVIDENCE_SCHEMA_VERSION = 2;
 /** @deprecated Use the document-specific schema version constants. */

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/doctor.js

@@ -314,7 +314,9 @@ function checkProjectLoop(manifest, config) {
         return undefined;
     }
     return manifest.harness.includes("agy")
-        ? check("project-loop", "DEGRADED", "agy loop uses only PreInvocation and PreToolUse(run_command); prompt, permission, compact, and subagent events are unavailable.")
+        ? 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) {

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

@@ -136,7 +136,7 @@ const DESCRIPTORS = {
             hookRegistered: (source, capabilities) => isAgyHookRegistered(parseJsonSource(source), capabilities),
             plan: async (context) => {
                 if (context.scope === "project") {
-                    return await planCommonHarnessContribution("codex", context);
+                    return await planCommonHarnessContribution("agy", context);
                 }
                 const descriptor = DESCRIPTORS.agy;
                 return {
@@ -281,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",
@@ -306,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/ownership.js

@@ -4,7 +4,7 @@ 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 === "agy" && manifest.scope === "project" ? "codex" : id);
+    const descriptor = manifestDescriptor(manifest, id);
     const markers = managedBlockMarkers(markerId, 1, "html");
     return {
         id: markerId,
@@ -20,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 {
@@ -98,7 +105,7 @@ export function assertSupportedManifestOwnership(manifest, root) {
         throw manifestOwnershipError();
     }
     for (const id of harnesses) {
-        const descriptor = harnessDescriptor(id === "agy" && manifest.scope === "project" ? "codex" : id);
+        const descriptor = manifestDescriptor(manifest, id);
         const artifactPath = `.agent-ops/${descriptor.control.instructionFile}`;
         const artifactKey = pathKey(artifactPath);
         const artifactEntry = expectedArtifactPaths.get(artifactKey);