@kylecheng3146/agent-ops 0.1.20 → 0.1.21

package/README.md

@@ -68,7 +68,8 @@ agent-ops uninstall --dry-run --json
 
 `loop` is an explicit, project-only profile for agy, Codex, and Claude Code.
 agy installs its native `PreInvocation`, `PreToolUse(run_command)`, and optional
-`Stop` subset directly in `.agents/hooks.json`; doctor reports its loop as
+`Stop` subset directly in `.agents/hooks.json`, plus project routing in
+`GEMINI.md` to `.agent-ops/GEMINI.md`; doctor reports its loop as
 degraded because prompt, permission, compact, and subagent events are unavailable.
 Claude Code supports native Windows through a generated PowerShell launcher;
 Codex's loop launcher still requires POSIX-compatible `bash`. Preview it
@@ -80,6 +81,24 @@ agent-ops init --dry-run --scope project --harness codex,claude --profile loop -
 agent-ops init --scope project --harness codex,claude --profile loop --yes
 ```
 
+For a project agy loop, the wizard recommends the hard completion gate. In
+automation, opt in explicitly:
+
+```bash
+agent-ops init --scope project --harness agy --profile loop --completion-gate --yes
+```
+
+The gate lets pure Q&A, analysis, and read-only diagnostics stop normally. It
+activates only after that conversation creates a Git-visible net change, then
+requires an attached completed task with two to five criteria, current PASS
+evidence, and a PASS review for the current source fingerprint. It never runs
+tests or review from `Stop`. Error, max-step, and non-idle stops continue. A
+user can approve one fingerprint-bound escape with
+`agent-ops allow-stop --session <conversationId>`. Use
+`agent-ops agy-run -- <agy arguments>` for a process-exit recheck in headless or
+CI use. Codex, Claude Code, and OpenCode retain their existing non-blocking Stop
+behavior in this release.
+
 On native Windows, select `--harness claude` unless Codex is running in a
 POSIX environment; the Codex loop still invokes `bash`.
 
@@ -250,10 +269,10 @@ After changing Stop configuration, run `agent-ops update`; its approved plan
 updates native registrations and the exact trust binding together. Stop is
 report-only: `PASS`, `FAIL`, and `UNKNOWN` continue
 the harness, emit bounded command evidence, and never complete a task.
-Config v1 migrates to config v2 with Stop disabled; migration invalidates the
-old trust binding, and pre-v1 binaries cannot read the migrated config.
+Older configs migrate to config v3 with both Stop verification and the agy
+completion gate disabled; migration invalidates the old trust binding.
 
-The generated `AGENTS.md` and `CLAUDE.md` routing blocks are supplemental: they
+The generated `AGENTS.md`, `CLAUDE.md`, and agy `GEMINI.md` routing blocks are supplemental: they
 load the managed baseline while leaving project-specific instructions in those
 files authoritative. Existing installations with the previous canonical
 wording are migrated by `agent-ops update`; changed managed blocks still fail

package/dist/packages/cli/src/agy-headless.js

@@ -0,0 +1,18 @@
+/** Headless wrapper: native Stop is bounded by agy, process exit is not. */
+export async function runAgyHeadless(options) {
+    await options.gate.initialize(options.sessionId);
+    const exitCode = await options.run(options.args, {
+        ...(options.env ?? process.env),
+        AGENT_OPS_SESSION_ID: options.sessionId
+    });
+    if (exitCode !== 0)
+        return exitCode;
+    const result = await options.gate.handle({
+        event: "stop",
+        projectRoot: options.root,
+        sessionId: options.sessionId,
+        terminationReason: "model_stop",
+        fullyIdle: true
+    });
+    return result?.action === "block" ? 2 : 0;
+}

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

@@ -8,7 +8,8 @@ export const COMMAND_NAMES = [
     "uninstall",
     "task",
     "verify",
-    "review"
+    "review",
+    "allow-stop"
 ];
 const COMMAND_SET = new Set(COMMAND_NAMES);
 const SCOPES = new Set(["project", "user"]);
@@ -73,6 +74,7 @@ export function parseArgs(argv) {
     const criteria = [];
     const evidence = [];
     let checkAuth = false;
+    let completionGate;
     let dryRun = false;
     let json = false;
     let yes = false;
@@ -203,6 +205,12 @@ export function parseArgs(argv) {
                 }
                 checkAuth = true;
                 break;
+            case "--completion-gate":
+                if (completionGate !== undefined) {
+                    duplicate(token);
+                }
+                completionGate = true;
+                break;
             case "--dry-run":
                 if (dryRun) {
                     duplicate(token);
@@ -291,6 +299,7 @@ export function parseArgs(argv) {
             criteria.length > 0 ||
             evidence.length > 0 ||
             reviewTargets.length > 0 ||
+            completionGate !== undefined ||
             sessionId !== undefined ||
             base !== undefined ||
             checkAuth ||
@@ -317,6 +326,7 @@ export function parseArgs(argv) {
     if (command !== "task" &&
         command !== "verify" &&
         command !== "review" &&
+        command !== "allow-stop" &&
         (hasTaskTargetOptions || hasTaskMutationOptions)) {
         throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Task target options may be used only with task or verify.");
     }
@@ -340,6 +350,9 @@ export function parseArgs(argv) {
     if (reviewTargets.length > 0 && command !== "init") {
         throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--review-target may be used only with init.");
     }
+    if (completionGate !== undefined && command !== "init") {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--completion-gate may be used only with init.");
+    }
     if (command === "task") {
         if (harness !== undefined ||
             profiles.length > 0 ||
@@ -349,8 +362,7 @@ export function parseArgs(argv) {
         }
         const taskOptionInvalid = (action === "create" &&
             (taskId !== undefined ||
-                evidence.length > 0 ||
-                sessionId !== undefined)) ||
+                evidence.length > 0)) ||
             (action === "status" &&
                 (title !== undefined ||
                     criteria.length > 0 ||
@@ -403,6 +415,19 @@ export function parseArgs(argv) {
     if (command === "review" && harness !== undefined && harness.length !== 1) {
         invalidValue("--harness", harness.join(","));
     }
+    if (command === "allow-stop" &&
+        (sessionId === undefined ||
+            scope !== undefined ||
+            harness !== undefined ||
+            taskId !== undefined ||
+            profiles.length > 0 ||
+            title !== undefined ||
+            criteria.length > 0 ||
+            evidence.length > 0 ||
+            dryRun ||
+            yes)) {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "allow-stop requires only --session (and optional --json).");
+    }
     return {
         command,
         ...(action === undefined ? {} : { action }),
@@ -415,6 +440,7 @@ export function parseArgs(argv) {
         ...(targetVersion === undefined ? {} : { targetVersion }),
         ...(title === undefined ? {} : { title }),
         ...(reviewTargets.length === 0 ? {} : { reviewTargets }),
+        ...(completionGate === undefined ? {} : { completionGate }),
         ...(criteria.length === 0 ? {} : { criteria }),
         ...(evidence.length === 0 ? {} : { evidence }),
         ...(sessionId === undefined ? {} : { sessionId }),

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

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { commonHarnessAdapters, harnessHookPath, HARNESS_IDS } from "../../../runtime/src/install/harness.js";
 import { agyRuntimeStatus, agyVersionSupported, hookRegistrationDrift, repositoryTrustStatus, smokeAvailabilityStatus } from "../../../runtime/src/install/probes.js";
@@ -33,8 +34,11 @@ import { probeReviewTarget } from "../../../runtime/src/review/probe.js";
 import { resolveReviewRole } from "../../../runtime/src/review/roles.js";
 import { runTrustCommand } from "./commands/trust.js";
 import { runVerifyCommand } from "./commands/verify.js";
+import { runAllowStopCommand } from "./commands/allow-stop.js";
+import { CompletionGateService } from "../../../runtime/src/hooks/completion-gate.js";
 import { formatUpdatePlan, runUpdateCommand } from "./commands/update.js";
 import { errorEnvelope } from "./output.js";
+import { runAgyHeadless } from "./agy-headless.js";
 const HOOK_RUNTIME_PATH = fileURLToPath(new URL("./hook-entry.js", import.meta.url));
 async function readOptionalText(path) {
     try {
@@ -122,7 +126,40 @@ function runAgy(args, options = {}) {
         ...(process.platform === "win32" ? { shell: true } : {})
     });
 }
-if (argv[0] === "hook") {
+if (argv[0] === "agy-run") {
+    try {
+        const root = process.cwd();
+        const config = (await loadEffectiveConfig(root, "project")).config;
+        if (!config.features.completionGate.enabled) {
+            throw new Error("agy-run requires features.completionGate.enabled.");
+        }
+        const taskService = new TaskService(new FileTaskStore(join(root, ".agent-ops", "tasks", "state.json"), root));
+        const gate = new CompletionGateService({
+            root,
+            config,
+            gitRunner: gitRunner(root),
+            taskService,
+            evidenceStore: new FileEvidenceStore(root, root)
+        });
+        const agyArgs = argv[1] === "--" ? argv.slice(2) : argv.slice(1);
+        process.exitCode = await runAgyHeadless({
+            root,
+            sessionId: `agy-headless-${randomUUID()}`,
+            args: agyArgs,
+            gate,
+            run: async (args, env) => await new Promise((resolve) => {
+                const child = spawn("agy", [...args], { cwd: root, env, stdio: "inherit" });
+                child.once("error", () => resolve(1));
+                child.once("exit", (code) => resolve(code ?? 1));
+            })
+        });
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : "agy-run failed."}\n`);
+        process.exitCode = 2;
+    }
+}
+else if (argv[0] === "hook") {
     process.exitCode = await runHookProcess(argv.slice(1), {
         stdin: process.stdin,
         writeStdout: (value) => process.stdout.write(value),
@@ -147,7 +184,8 @@ else {
             "uninstall",
             "task",
             "verify",
-            "review"
+            "review",
+            "allow-stop"
         ].map((command) => [command, async (args) => {
                 const root = args.scope === "user"
                     ? process.env.AGENT_OPS_HOME ?? homedir()
@@ -316,6 +354,19 @@ else {
                     });
                 }
                 const taskService = new TaskService(new FileTaskStore(join(root, ".agent-ops", "tasks", "state.json"), root));
+                if (args.command === "allow-stop") {
+                    const config = (await loadEffectiveConfig(root, "project")).config;
+                    return await runAllowStopCommand({
+                        args,
+                        gate: new CompletionGateService({
+                            root,
+                            config,
+                            gitRunner: gitRunner(root),
+                            taskService,
+                            evidenceStore: new FileEvidenceStore(root, root)
+                        })
+                    });
+                }
                 if (args.command === "task") {
                     const sessionId = process.env.AGENT_OPS_SESSION_ID;
                     const policyConfigHash = args.action === "create"

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

@@ -27,6 +27,8 @@ Commands:
              Manage independent task acceptance state
   verify     Run configured verification
   review     Run an independent review
+  allow-stop Grant one fingerprint-bound agy Stop permit (requires --session)
+  agy-run    Run headless agy with a process-exit completion recheck
 
 Options:
   --scope <project|user>
@@ -35,6 +37,7 @@ Options:
   --profile <core|advisory|guardrails|loop>  Repeatable
   --review-target <codex|agy|claude>  Repeatable init option; external review
                                       targets in fallback-chain order
+  --completion-gate                  Init only: enable the agy project-loop gate
   --check-auth                        Doctor only: probe each review target's
                                       authentication with one real call
   --task <id>

package/dist/packages/cli/src/commands/allow-stop.js

@@ -0,0 +1,11 @@
+import { AgentOpsError } from "../../../../runtime/src/fs/paths.js";
+import { okEnvelope } from "../output.js";
+export async function runAllowStopCommand(options) {
+    if (options.args.command !== "allow-stop" || options.args.sessionId === undefined) {
+        throw new AgentOpsError("COMPLETION_GATE_SESSION_REQUIRED", "allow-stop requires --session.");
+    }
+    await options.gate.grantPermit(options.args.sessionId);
+    return okEnvelope("COMPLETION_GATE_PERMIT_GRANTED", {
+        message: "One Stop is permitted for this conversation and current source fingerprint."
+    });
+}

package/dist/packages/cli/src/commands/hook.js

@@ -49,11 +49,22 @@ export async function runHookCommand(options) {
             capabilities,
             trusted: options.trusted,
             advisory: options.advisory ?? runLifecycleAdvisory,
-            ...(stopVerification === undefined ? {} : { stopVerification })
+            ...(stopVerification === undefined ? {} : { stopVerification }),
+            ...(options.completionGate === undefined
+                ? {}
+                : { completionGate: options.completionGate })
         });
         return descriptor.runtime.formatOutput(options.event, result);
     }
     catch {
+        if (options.harness === "agy" && options.completionGate !== undefined) {
+            return harnessDescriptor("agy").runtime.formatOutput(options.event, {
+                action: "block",
+                status: "UNKNOWN",
+                code: "COMPLETION_GATE_UNAVAILABLE",
+                remedy: "Run agent-ops doctor; a user-approved one-time permit may be used after diagnosing the failure."
+            });
+        }
         return { exitCode: 0, stdout: "", stderr: "" };
     }
 }

package/dist/packages/cli/src/commands/init.js

@@ -102,7 +102,10 @@ export async function runInitCommand(options) {
             : { hookTargets: options.hookTargets ?? args.hookTargets }),
         ...(args.reviewTargets === undefined
             ? {}
-            : { reviewTargets: args.reviewTargets })
+            : { reviewTargets: args.reviewTargets }),
+        ...(args.completionGate === undefined
+            ? {}
+            : { completionGateEnabled: args.completionGate })
     });
     const trust = await trustChange(options, plan);
     const warnings = plan.harness.includes("agy") && options.agyWarning !== undefined

package/dist/packages/cli/src/commands/task.js

@@ -95,9 +95,12 @@ export async function runTaskCommand(options) {
                     : { policyConfigHash: options.policyConfigHash }),
                 ...(options.args.parentTaskId === undefined
                     ? {}
-                    : { parentTaskId: options.args.parentTaskId })
+                    : { parentTaskId: options.args.parentTaskId }),
+                ...(sessionId === undefined ? {} : { sessionId })
             });
-            return taskEnvelope(action, "TASK_CREATED", `Created task ${record.task.id}.`, record);
+            return taskEnvelope(action, "TASK_CREATED", sessionId === undefined
+                ? `Created task ${record.task.id}.`
+                : `Created and attached task ${record.task.id}.`, record);
         }
         if (action === "status") {
             if (options.args.taskId === undefined && sessionId === undefined) {

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

@@ -9,12 +9,15 @@ import { AgentOpsError } from "../../../runtime/src/fs/paths.js";
 import { localStatePaths } from "../../../runtime/src/security/permissions.js";
 import { calculateTrustBinding, FileTrustStore } from "../../../runtime/src/security/trust.js";
 export const DEFAULT_CONFIG = {
-    schemaVersion: 2,
+    schemaVersion: 3,
     profiles: [],
     verification: { commands: [] },
     features: {
         stopVerification: {
             enabled: false
+        },
+        completionGate: {
+            enabled: false
         }
     },
     pathMappings: [],

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