@kylecheng3146/agent-ops 0.1.20 → 0.1.21

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);

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: {
@@ -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/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/schema/validate.js

@@ -328,7 +328,7 @@ export function validateConfig(value) {
     if (!isRecord(root.features)) {
         return failure("INVALID_TYPE", "$.features", "features must be an object.");
     }
-    const featuresUnknown = unknownFieldFailure(root.features, ["stopVerification"], "$.features");
+    const featuresUnknown = unknownFieldFailure(root.features, ["completionGate", "stopVerification"], "$.features");
     if (featuresUnknown !== undefined) {
         return featuresUnknown;
     }
@@ -342,6 +342,16 @@ export function validateConfig(value) {
     if (typeof root.features.stopVerification.enabled !== "boolean") {
         return failure("INVALID_FEATURE", "$.features.stopVerification.enabled", "stopVerification.enabled must be a boolean.");
     }
+    if (!isRecord(root.features.completionGate)) {
+        return failure("INVALID_TYPE", "$.features.completionGate", "completionGate must be an object.");
+    }
+    const completionGateUnknown = unknownFieldFailure(root.features.completionGate, ["enabled"], "$.features.completionGate");
+    if (completionGateUnknown !== undefined) {
+        return completionGateUnknown;
+    }
+    if (typeof root.features.completionGate.enabled !== "boolean") {
+        return failure("INVALID_FEATURE", "$.features.completionGate.enabled", "completionGate.enabled must be a boolean.");
+    }
     if (!isRecord(root.verification)) {
         return failure("INVALID_TYPE", "$.verification", "verification must be an object.");
     }

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

@@ -77,6 +77,9 @@ export class TaskService {
             !/^[a-f0-9]{64}$/u.test(input.policyConfigHash)) {
             throw taskError("TASK_POLICY_CONFIG_INVALID", "Policy config hash must be a lowercase SHA-256 digest.");
         }
+        if (input.sessionId !== undefined) {
+            assertSessionId(input.sessionId);
+        }
         const task = {
             schemaVersion: TASK_SCHEMA_VERSION,
             id: this.#generateId(),
@@ -118,6 +121,20 @@ export class TaskService {
                 policyConfigHash: input.policyConfigHash ?? null
             };
             state.tasks.push(record);
+            if (input.sessionId !== undefined) {
+                const currentIndex = state.sessions.findIndex(({ sessionId }) => sessionId === input.sessionId);
+                const attachment = {
+                    sessionId: input.sessionId,
+                    taskId: record.task.id,
+                    attachedAt: now
+                };
+                if (currentIndex === -1) {
+                    state.sessions.push(attachment);
+                }
+                else {
+                    state.sessions[currentIndex] = attachment;
+                }
+            }
             return cloneRecord(record);
         });
     }

package/docs/en/guides/configuration.md

@@ -6,10 +6,12 @@ Use `--harness all` to select agy, Codex, Claude Code, and opencode, or pass a
 comma-separated subset such as `codex,opencode`. `both` remains an input alias
 for the legacy Codex plus Claude selection.
 
-Project agy, Codex, and opencode installations share the managed supplemental
-`AGENTS.md` routing block and the `.agent-ops/AGENTS.md` rules artifact. The
-block loads the managed baseline while project-specific instructions remain
-authoritative. Claude uses the corresponding `CLAUDE.md` route and
+Project agy uses a managed supplemental `GEMINI.md` routing block and
+`.agent-ops/GEMINI.md` baseline. This follows the official agy CLI rule that a
+workspace-root `GEMINI.md` or `AGENTS.md` is loaded at startup. Codex and
+opencode share the corresponding `AGENTS.md` route and `.agent-ops/AGENTS.md`
+artifact. Each block loads the managed baseline while project-specific
+instructions remain authoritative. Claude uses the corresponding `CLAUDE.md` route and
 `.agent-ops/CLAUDE.md` artifact. Opencode additionally gets
 the agent-ops-owned `.opencode/plugins/agent-ops.js` file; `opencode.json` is
 never modified. The plugin is generated with the installed absolute runtime
@@ -147,6 +149,21 @@ user hooks live in `.gemini/config/hooks.json`. User-scope rules modify the
 shared Gemini rule surface at `.gemini/GEMINI.md`. agy 1.1.12 or newer is
 required for machine-readable `/hooks` diagnostics.
 
+For `agy` plus `loop`, the interactive installer recommends
+`features.completionGate.enabled`; non-interactive installs require the explicit
+`--completion-gate` flag. The gate uses the documented `conversationId`,
+`terminationReason`, and `fullyIdle` Stop fields and returns the documented
+`decision: "continue"` only for a final changed conversation that lacks current
+task, verification, or review proof. Pure Q&A, analysis, read-only diagnostics,
+error stops, max-step stops, and non-idle stops continue normally. It does not
+change Codex, Claude Code, or OpenCode Stop behavior. For headless execution use
+`agent-ops agy-run -- <agy arguments>`; a user-approved one-time escape is
+`agent-ops allow-stop --session <conversationId>` and is guarded by agy's
+documented `force_ask` decision.
+
+Official references: [agy CLI workspace rule files](https://www.antigravity.google/docs/cli/best-practices/)
+and [Antigravity hook contracts](https://www.antigravity.google/docs/hooks/).
+
 The full Codex/Claude loop runs `SessionStart`, `UserPromptSubmit`, `PreToolUse`,
 `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`,
 `SubagentStart`, and `SubagentStop`, but never adds `Stop`. It blocks only
@@ -183,8 +200,9 @@ 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.
+proof that a host honors a denial. `SessionStart` and ordinary Stop verification
+failure paths stay fail-open. Only the explicitly enabled agy completion gate
+fails closed at final Stop.
 
 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
@@ -196,7 +214,7 @@ 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
+is a separate config-v3 feature and must be explicitly enabled with at least
 one confirmed command:
 
 ```json

package/docs/en/spec/README.md

@@ -4,12 +4,12 @@ This is the normative English specification for bounded, evidence-driven work.
 
 The harness adapter rules cover agy, Codex, Claude Code, and opencode. The
 opencode integration is a generated local plugin; it does not manage
-`opencode.json`. agy shares project `AGENTS.md` routing, uses native hooks, and
+`opencode.json`. agy uses project `GEMINI.md` routing, uses native hooks, and
 is explicitly degraded where its lifecycle surface is smaller than the full
 loop.
 
-Configuration is versioned independently from the manifest. Config v1 migrates
-to config v2 with Stop verification disabled; changing the capability requires
+Configuration is versioned independently from the manifest. Older configs migrate
+to config v3 with Stop verification and the agy completion gate disabled; changing a capability requires
 a confirmed project `agent-ops update`, which also refreshes trust when
 verifiers exist. Stop verification is
 explicit, trusted, report-only, and never completes a task. Dry-run plans keep

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

@@ -108,6 +108,7 @@ The current registration matrix is intentionally asymmetric:
 | --- | --- | --- | --- | --- |
 | lifecycle-summary | degraded | supported | supported | degraded |
 | command-policy | supported | unknown | supported | supported |
+| completion-gate | supported | unsupported | unsupported | unsupported |
 | optional-stop-verify | degraded | unsupported | supported | degraded |
 
 For runtime-failure handling, only `command-policy` is fail-closed. Claude
@@ -118,11 +119,14 @@ 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.
 
-The agy adapter uses project `AGENTS.md` routing alongside Codex and OpenCode;
+The agy adapter uses native project `GEMINI.md` routing to
+`.agent-ops/GEMINI.md`;
 at user scope it manages `.agent-ops/GEMINI.md` and a managed block in the
 shared `.gemini/GEMINI.md` rule surface. Its native hooks use camelCase input,
-return `decision: "deny"` for command-policy blocks, and never force a Stop
-continuation. On Windows the generated command is invoked through `cmd /c`.
+return `decision: "deny"` for command-policy blocks, and, only when the
+completion gate is explicitly enabled, return `decision: "continue"` for an
+unproven final changed conversation. Read-only conversations stop normally.
+On Windows the generated command is invoked through `cmd /c`.
 
 Stop verification is explicit, trusted, report-only, and disabled by default.
 Every Stop result continues the native harness and may carry only bounded