@kylecheng3146/agent-ops 0.1.22 → 0.2.0

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

@@ -284,8 +284,27 @@ export function parseArgs(argv) {
     if (helpSeen && versionSeen) {
         throw new CliArgumentError("CLI_CONFLICTING_ACTION", "--help and --version cannot be combined.");
     }
-    if ((helpSeen || versionSeen) && command !== undefined) {
-        throw new CliArgumentError("CLI_CONFLICTING_ACTION", "Global help or version cannot be combined with a command.");
+    // `<command> --help` asks about that command, so it answers instead of
+    // failing: an agent that cannot read a command's own option shapes guesses
+    // at them one rejected call at a time. Other options are ignored rather than
+    // rejected, so `task create --criterion <wrong> --help` still explains the
+    // shape it got wrong.
+    if (helpSeen &&
+        command !== undefined &&
+        command !== "help" &&
+        command !== "version") {
+        return {
+            command: "help",
+            helpTopic: command,
+            ...(action === undefined ? {} : { helpAction: action }),
+            profiles: [],
+            dryRun: false,
+            json,
+            yes: false
+        };
+    }
+    if (versionSeen && command !== undefined) {
+        throw new CliArgumentError("CLI_CONFLICTING_ACTION", "Global version cannot be combined with a command.");
     }
     if (helpSeen || versionSeen) {
         if (scope !== undefined ||
@@ -336,8 +355,9 @@ export function parseArgs(argv) {
     if (command !== "update" && targetVersion !== undefined) {
         throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--target-version may be used only with update.");
     }
-    if (base !== undefined && command !== "verify" && command !== "review") {
-        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--base may be used only with verify or review.");
+    if (base !== undefined && command !== "verify" && command !== "review" &&
+        !(command === "task" && action === "complete")) {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--base may be used only with verify, review or task complete.");
     }
     if (hookTargets.length > 0 &&
         command !== "init" &&
@@ -401,9 +421,8 @@ export function parseArgs(argv) {
             evidence.length > 0 ||
             dryRun ||
             yes ||
-            base !== undefined ||
             (taskId !== undefined && sessionId !== undefined))) {
-        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Verify accepts only scope, task or session, and json options.");
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Verify accepts only scope, task or session, base, and json options.");
     }
     if (command === "review" &&
         (title !== undefined || sessionId !== undefined)) {

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

@@ -353,7 +353,12 @@ else {
                             : { targetVersion: updateArgs.targetVersion })
                     });
                 }
-                const taskService = new TaskService(new FileTaskStore(join(root, ".agent-ops", "tasks", "state.json"), root));
+                const taskService = new TaskService(new FileTaskStore(join(root, ".agent-ops", "tasks", "state.json"), root), { completion: {
+                        root,
+                        gitRunner: gitRunner(root),
+                        ...(args.base === undefined ? {} : { base: args.base }),
+                        loadConfig: async () => (await loadEffectiveConfig(root, args.scope === "user" ? "user" : "project")).config
+                    } });
                 if (args.command === "allow-stop") {
                     const config = (await loadEffectiveConfig(root, "project")).config;
                     return await runAllowStopCommand({

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

@@ -27,7 +27,7 @@ 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)
+  allow-stop Grant one fingerprint-bound completion-gate Stop permit (requires --session)
   agy-run    Run headless agy with a process-exit completion recheck
 
 Options:
@@ -37,7 +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
+  --completion-gate                  Init only: enable the project-loop completion gate
   --check-auth                        Doctor only: probe each review target's
                                       authentication with one real call
   --task <id>
@@ -48,13 +48,141 @@ Options:
   --criterion <json>                    Repeatable
   --evidence <criterion-id=reference>   Repeatable
   --session <id>
-  --base <git-ref>                    Verify/review a clean committed range
+  --base <git-ref>                    Verify/review/complete a clean committed range
   --dry-run
   --json
   --yes
   --help
   --version
 `;
+/**
+ * What `<command> --help` answers. Each entry states the option shapes that
+ * command actually accepts, because the global list cannot say which options
+ * belong to which command — and a caller that guesses learns only by being
+ * rejected.
+ */
+export const COMMAND_HELP_TEXT = {
+    init: `Usage: agent-ops init [options]
+
+Plan or install agent-ops into this repository.
+
+Options:
+  --scope <project|user>
+  --harness <all|both|agy|claude|codex|opencode|comma-separated>
+  --hook-target <harness=surface-id>   Repeatable
+  --profile <core|advisory|guardrails|loop>  Repeatable
+  --review-target <codex|agy|claude>   Repeatable, in fallback-chain order
+  --completion-gate                    Enable the project-loop completion gate
+  --dry-run                            Print the plan without writing
+  --json
+  --yes
+`,
+    config: `Usage: agent-ops config explain [options]
+
+Show where each effective configuration value came from.
+
+Options:
+  --scope <project|user>
+  --json
+`,
+    trust: `Usage: agent-ops trust <status|grant|revoke> [options]
+
+Manage the explicit trust record this repository's commands require.
+
+Options:
+  --scope <project|user>
+  --json
+  --yes
+`,
+    doctor: `Usage: agent-ops doctor [options]
+
+Diagnose the installation and report remediation for each failed check.
+
+Options:
+  --scope <project|user>
+  --harness <all|both|agy|claude|codex|opencode|comma-separated>
+  --check-auth   Probe each review target's authentication with one real call
+  --json
+`,
+    update: `Usage: agent-ops update [options]
+
+Update managed artifacts to this toolkit version.
+
+Options:
+  --scope <project|user>
+  --harness <all|both|agy|claude|codex|opencode|comma-separated>
+  --target-version <version>   Offline-capable update target
+  --dry-run
+  --json
+  --yes
+`,
+    uninstall: `Usage: agent-ops uninstall [options]
+
+Remove managed artifacts, leaving foreign handlers in place.
+
+Options:
+  --scope <project|user>
+  --harness <all|both|agy|claude|codex|opencode|comma-separated>
+  --dry-run
+  --json
+  --yes
+`,
+    task: `Usage: agent-ops task <create|status|attach|complete|archive|export> [options]
+
+Manage independent task acceptance state. Task commands accept none of
+--harness, --profile, --dry-run or --yes.
+
+Options:
+  --title <text>                        create
+  --criterion <json>                    create, repeatable, two to five total
+  --parent <task-id>                    create: record a subtask; status: list subtasks
+  --task <id>                           status, attach, complete, archive, export
+  --session <id>                        attach, status
+  --evidence <criterion-id=reference>   complete, repeatable
+  --base <git-ref>                      complete: a clean committed range
+  --json
+
+Each --criterion is one JSON object with exactly these keys:
+
+  {"id":"kebab-id","description":"what must hold","verifierIds":["node-test"]}
+
+Every criterion needs at least one verifierIds entry naming a verification
+command id configured in .agent-ops/config.json. No other key is accepted.
+`,
+    verify: `Usage: agent-ops verify [options]
+
+Run the configured verification commands and record their evidence.
+
+Options:
+  --task <id>
+  --session <id>
+  --base <git-ref>   Verify a clean committed range
+  --json
+`,
+    review: `Usage: agent-ops review [options]
+
+Run one independent read-only review against the configured target chain.
+
+Options:
+  --task <id>
+  --session <id>
+  --criterion <id>     Repeatable: review only these task criteria
+  --harness <target>   One configured review target
+  --base <git-ref>
+  --json
+  --yes                Authorize the review call
+`,
+    "allow-stop": `Usage: agent-ops allow-stop --session <id> [options]
+
+Grant one fingerprint-bound Stop permit for the completion gate, on agy or
+Claude Code. Requires user approval: the PreToolUse hook asks the user, so an
+agent cannot self-authorize it.
+
+Options:
+  --session <id>   Required
+  --json
+`
+};
 function wantsJson(argv) {
     return argv.includes("--json");
 }
@@ -80,7 +208,11 @@ export async function runCli(argv, io, services) {
         return writeAndReturn(io, errorEnvelope("CLI_INTERNAL_ERROR", "Unable to parse command arguments."), json, 1);
     }
     if (args.command === "help") {
-        return writeAndReturn(io, okEnvelope("CLI_HELP", { text: HELP_TEXT }), args.json, 0);
+        const topic = args.helpTopic;
+        return writeAndReturn(io, okEnvelope("CLI_HELP", {
+            text: topic === undefined ? HELP_TEXT : COMMAND_HELP_TEXT[topic],
+            ...(topic === undefined ? {} : { topic })
+        }), args.json, 0);
     }
     if (args.command === "version") {
         return writeAndReturn(io, okEnvelope("CLI_VERSION", { version: services.version }), args.json, 0);

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

@@ -20,25 +20,20 @@ export function normalizeHookInput(harness, input) {
     }
 }
 /**
- * Hooks are advisory infrastructure: every failure path stays fail-open with
- * exit code 0 so a broken toolkit can never wedge the harness.
+ * Advisory failures stay fail-open; an enabled completion Stop fails closed
+ * through the host's native decision protocol (still exit code 0).
  */
 export async function runHookCommand(options) {
     try {
         const { capabilities } = options.config.profiles.length === 0
             ? { capabilities: [] }
             : resolveCapabilities(options.config);
-        let input;
-        try {
-            input = JSON.parse(options.stdin);
-        }
-        catch {
-            return { exitCode: 0, stdout: "", stderr: "" };
-        }
+        const input = JSON.parse(options.stdin);
         const descriptor = harnessDescriptor(options.harness);
         const normalized = normalizeHookInput(options.harness, input);
-        if (normalized === null) {
-            return { exitCode: 0, stdout: "", stderr: "" };
+        if (normalized === null ||
+            (options.completionGate !== undefined && options.event === "Stop" && normalized.event !== "stop")) {
+            throw new Error("Invalid hook input.");
         }
         const stopRegistration = descriptor.control.registrations.find(({ capability }) => capability === "optional-stop-verify");
         const stopVerification = options.stopVerification !== undefined &&
@@ -57,8 +52,12 @@ export async function runHookCommand(options) {
         return descriptor.runtime.formatOutput(options.event, result);
     }
     catch {
-        if (options.harness === "agy" && options.completionGate !== undefined) {
-            return harnessDescriptor("agy").runtime.formatOutput(options.event, {
+        // Fail closed on every host that enforces the gate: an exception here is
+        // exactly the case where a silent empty output would wave the stop through.
+        if ((options.harness === "agy" || options.harness === "claude") &&
+            options.event === "Stop" &&
+            options.completionGate !== undefined) {
+            return harnessDescriptor(options.harness).runtime.formatOutput(options.event, {
                 action: "block",
                 status: "UNKNOWN",
                 code: "COMPLETION_GATE_UNAVAILABLE",

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

@@ -108,17 +108,30 @@ export async function runInitCommand(options) {
             : { completionGateEnabled: args.completionGate })
     });
     const trust = await trustChange(options, plan);
-    const warnings = plan.harness.includes("agy") && options.agyWarning !== undefined
-        ? (() => {
-            try {
-                const warning = options.agyWarning();
-                return warning === undefined ? [] : [warning];
-            }
-            catch {
-                return ["agy could not be probed; run `agent-ops doctor` to verify it."];
-            }
-        })()
+    // An installation with no verifier looks finished and is not: every task
+    // completion needs current PASS evidence from a required verifier, so the
+    // loop can never close. Detection stays conservative on purpose — it will
+    // not guess a test command — which makes saying so out loud the whole fix.
+    const verificationWarnings = plan.config.verification.commands.length === 0
+        ? [
+            "No verification command is configured, so no task can be completed. " +
+                "Add verification.commands to .agent-ops/config.json." +
+                (plan.verificationBlockers.length === 0
+                    ? ""
+                    : ` Detection stopped because — ${plan.verificationBlockers.join("; ")}`)
+        ]
         : [];
+    const warnings = [...verificationWarnings, ...(plan.harness.includes("agy") && options.agyWarning !== undefined
+            ? (() => {
+                try {
+                    const warning = options.agyWarning();
+                    return warning === undefined ? [] : [warning];
+                }
+                catch {
+                    return ["agy could not be probed; run `agent-ops doctor` to verify it."];
+                }
+            })()
+            : [])];
     if (args.dryRun) {
         return okEnvelope("INIT_PLAN_READY", {
             applied: false,

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

@@ -1,7 +1,7 @@
 import { buildReviewPacket } from "../../../../runtime/src/review/packet.js";
 import { runIndependentReview } from "../../../../runtime/src/review/runner.js";
 import { renderReviewResult } from "../../../../runtime/src/review/render.js";
-import { saveReviewAttestation } from "../../../../runtime/src/review/attestation.js";
+import { invalidateReviewAttestation, saveReviewAttestation } from "../../../../runtime/src/review/attestation.js";
 import { resolveReviewRole } from "../../../../runtime/src/review/roles.js";
 import { AgentOpsError } from "../../../../runtime/src/fs/paths.js";
 import { assertSafeSupportingPaths, isReviewerPolicyPath, resolveReviewScope, reviewScopeSignature } from "../../../../runtime/src/review/scope.js";
@@ -75,7 +75,8 @@ async function taskContext(options) {
         policyConfigHash: record.policyConfigHash,
         evidence: record.evidence,
         failureFingerprint: record.failureFingerprint,
-        criteria
+        criteria,
+        allCriteriaReviewed: criteria.length === record.task.criteria.length
     };
 }
 function newestEvidence(values) {
@@ -123,11 +124,16 @@ async function currentEvidence(options, context, criterionId, commandId, configH
     return { current, hasReference, unreadable, stale };
 }
 async function preflightReview(options, context, sourceFingerprint) {
+    // A recorded failure is not stale evidence, and saying so sends the caller
+    // to re-run the verifier that just failed. The tests failed; that is the
+    // report.
+    if (context.failureFingerprint !== null) {
+        return { ok: false, reason: "verification-not-passed" };
+    }
     if (options.config === undefined ||
         options.evidenceStore === undefined ||
         options.root === undefined ||
-        options.gitRunner === undefined ||
-        context.failureFingerprint !== null) {
+        options.gitRunner === undefined) {
         return { ok: false, reason: "stale-verification" };
     }
     const configHash = calculateConfigHash(options.config);
@@ -287,6 +293,9 @@ export async function runReviewCommand(options) {
             });
         }
         sourceFingerprint = await calculateSourceFingerprint(options.root, scope, options.gitRunner);
+        if (options.authorized) {
+            await invalidateReviewAttestation(options.root, sourceFingerprint);
+        }
         if (context !== undefined && options.policyConfigHash !== undefined) {
             if (context.policyConfigHash === null) {
                 return notRunEnvelope({
@@ -422,7 +431,8 @@ export async function runReviewCommand(options) {
     // changes again.
     if (options.root !== undefined &&
         result.status === "PASS" &&
-        sourceFingerprint !== undefined) {
+        sourceFingerprint !== undefined &&
+        (context === undefined || context.allCriteriaReviewed)) {
         await saveReviewAttestation(options.root, {
             schemaVersion: 1,
             ...(context === undefined ? {} : { taskId: context.taskId }),

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

@@ -214,7 +214,11 @@ function shouldBuildStopVerification(harness, event, config, rawInput) {
  */
 export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
     const [harness, event] = argv;
-    const completionGateInstalled = harness === "agy" &&
+    // Both hosts whose Stop hook can actually refuse a stop. codex never fires
+    // Stop under `codex exec` and rejects `permissionDecision:ask`, so its
+    // escape hatch could not be user-approved; opencode can only deny a tool
+    // call, never a stop.
+    const completionGateInstalled = (harness === "agy" || harness === "claude") &&
         event === "Stop" &&
         argv.includes("--completion-gate");
     if (harness === undefined ||
@@ -230,7 +234,7 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
         const hookEvent = event;
         if (process.env.AGENT_OPS_DISABLE === "1") {
             if (completionGateInstalled) {
-                writeHookOutput(io, harnessDescriptor("agy").runtime.formatOutput("Stop", {
+                writeHookOutput(io, harnessDescriptor(harness).runtime.formatOutput("Stop", {
                     action: "block",
                     status: "UNKNOWN",
                     code: "COMPLETION_GATE_DISABLE_REJECTED",
@@ -246,7 +250,7 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
         const configOutcome = await hookConfigOutcome(root, dependencies.loadConfig);
         if (configOutcome.kind === "invalid") {
             if (completionGateInstalled) {
-                writeHookOutput(io, harnessDescriptor("agy").runtime.formatOutput("Stop", {
+                writeHookOutput(io, harnessDescriptor(harness).runtime.formatOutput("Stop", {
                     action: "block",
                     status: "UNKNOWN",
                     code: "COMPLETION_GATE_CONFIG_INVALID",
@@ -267,6 +271,15 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
             return 0;
         }
         const config = configOutcome.config;
+        if (completionGateInstalled && !config.features.completionGate.enabled) {
+            writeHookOutput(io, harnessDescriptor(harness).runtime.formatOutput("Stop", {
+                action: "block",
+                status: "UNKNOWN",
+                code: "COMPLETION_GATE_CONFIG_DISABLED",
+                remedy: "Restore completionGate.enabled or explicitly uninstall the completion gate."
+            }));
+            return 0;
+        }
         const trustStatus = dependencies.trust === undefined
             ? await repositoryTrust(root, config, cliVersion)
             : await dependencies.trust(root, config, cliVersion);
@@ -284,7 +297,12 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
                 processRunner
             })
             : undefined;
-        const completionGate = harnessId === "agy" && config.features.completionGate.enabled
+        // Not `completionGateInstalled`: that is the Stop handler's own marker,
+        // and the gate also answers PreToolUse — where it turns a self-issued
+        // `allow-stop` into a question for the user. Narrowing this to Stop takes
+        // the escape hatch's approval step away.
+        const completionGate = (harnessId === "agy" || harnessId === "claude") &&
+            config.features.completionGate.enabled
             ? dependencies.completionGate ?? {
                 handle: async (normalized) => await new CompletionGateService({
                     root,
@@ -311,7 +329,7 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
     }
     catch {
         if (completionGateInstalled) {
-            writeHookOutput(io, harnessDescriptor("agy").runtime.formatOutput("Stop", {
+            writeHookOutput(io, harnessDescriptor(harness).runtime.formatOutput("Stop", {
                 action: "block",
                 status: "UNKNOWN",
                 code: "COMPLETION_GATE_UNAVAILABLE",

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

@@ -24,7 +24,13 @@ export function claudeSettingsTarget(scope) {
             requiresWorkspaceTrust: false
         };
 }
-function commandHook(event, runtimePath) {
+/**
+ * The gate flag trails the ownership marker rather than preceding it, unlike
+ * agy's flat command string. The marker's position is what identifies a
+ * managed handler here, and moving it would make every existing installation
+ * read as foreign.
+ */
+function commandHook(event, runtimePath, completionGate = false) {
     return {
         type: "command",
         command: "node",
@@ -32,15 +38,16 @@ function commandHook(event, runtimePath) {
             runtimePath,
             "claude",
             event,
-            CLAUDE_HOOK_MARKER
+            CLAUDE_HOOK_MARKER,
+            ...(completionGate ? ["--completion-gate"] : [])
         ],
         timeout: 30
     };
 }
-function matcherGroup(event, runtimePath) {
+function matcherGroup(event, runtimePath, completionGate = false) {
     return {
         ...(event === "PreToolUse" ? { matcher: "Bash" } : {}),
-        hooks: [commandHook(event, runtimePath)]
+        hooks: [commandHook(event, runtimePath, completionGate)]
     };
 }
 function powershellLoopCommand(event) {
@@ -82,6 +89,21 @@ export function buildClaudeHookSettings(capabilities, runtimePath, platform = pr
         for (const event of CLAUDE_LOOP_EVENTS) {
             hooks[event] = [loopMatcherGroup(event, platform)];
         }
+        // The loop launcher runs a different process, and the completion gate does
+        // not live there. Its PreToolUse role is narrow but load-bearing: it is
+        // what turns a self-issued `allow-stop` into a question for the user, so
+        // the gate needs a handler of its own beside the loop's.
+        if (capabilities.includes("completion-gate")) {
+            // SessionStart for the same reason: the gate records its per-session
+            // baseline there, and a gate that never sees a session start refuses
+            // every stop as uninitialized.
+            for (const event of ["SessionStart", "PreToolUse"]) {
+                hooks[event] = [
+                    ...(hooks[event] ?? []),
+                    matcherGroup(event, runtimePath)
+                ];
+            }
+        }
     }
     else {
         if (capabilities.includes("lifecycle-summary")) {
@@ -91,7 +113,12 @@ export function buildClaudeHookSettings(capabilities, runtimePath, platform = pr
             hooks.PreToolUse = [matcherGroup("PreToolUse", runtimePath)];
         }
     }
-    if (capabilities.includes("optional-stop-verify")) {
+    // The gate supersedes report-only Stop verification: one managed Stop
+    // handler, and the gated one already reports everything the other would.
+    if (capabilities.includes("completion-gate")) {
+        hooks.Stop = [matcherGroup("Stop", runtimePath, true)];
+    }
+    else if (capabilities.includes("optional-stop-verify")) {
         hooks.Stop = [matcherGroup("Stop", runtimePath)];
     }
     return { hooks };
@@ -99,6 +126,28 @@ export function buildClaudeHookSettings(capabilities, runtimePath, platform = pr
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+/**
+ * The argument vector `commandHook` produces, and nothing else. The ownership
+ * marker alone is not proof: it is a plain string anyone may write, and a
+ * handler mistaken for ours is a handler `update` rewrites and `uninstall`
+ * deletes.
+ */
+function isManagedNodeArgs(args) {
+    if (!Array.isArray(args) || args.length < 4 || args.length > 5) {
+        return false;
+    }
+    const [runtimePath, harness, event, marker, gate] = args;
+    // The event is checked for shape, not membership: a handler an older
+    // agent-ops wrote for an event this version no longer knows is still ours to
+    // remove, and rejecting it would orphan it in the user's settings forever.
+    return (typeof runtimePath === "string" &&
+        runtimePath.length > 0 &&
+        harness === "claude" &&
+        typeof event === "string" &&
+        event.length > 0 &&
+        marker === CLAUDE_HOOK_MARKER &&
+        (gate === undefined || gate === "--completion-gate"));
+}
 /**
  * Matches only the two command shapes agent-ops actually generates. This is
  * reused by installation inspection so a foreign hook cannot masquerade as
@@ -109,11 +158,12 @@ export function isClaudeManagedHandler(handler) {
         return false;
     }
     return ((handler.command === "node" &&
-        Array.isArray(handler.args) &&
-        handler.args[3] === CLAUDE_HOOK_MARKER) ||
+        isManagedNodeArgs(handler.args)) ||
         (handler.command === "bash" &&
             Array.isArray(handler.args) &&
+            handler.args.length === 3 &&
             handler.args[0] === CLAUDE_LOOP_LAUNCHER &&
+            CLAUDE_LOOP_EVENTS.includes(handler.args[1]) &&
             handler.args[2] === CLAUDE_HOOK_MARKER) ||
         (handler.shell === "powershell" &&
             handler.args === undefined &&

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

@@ -37,5 +37,13 @@ export const CLAUDE_CAPABILITY_REGISTRATIONS = [
         surfaceId: "claude-settings",
         support: "supported",
         runtimeFailure: "fail-open"
+    },
+    {
+        capability: "completion-gate",
+        normalizedEvent: "stop",
+        nativeEvent: "Stop",
+        surfaceId: "claude-settings",
+        support: "supported",
+        runtimeFailure: "fail-closed"
     }
 ];

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

@@ -13,17 +13,31 @@ export function normalizeClaudeHookInput(input) {
         return normalizeHookEvent(input);
     }
     const projectRoot = input.cwd;
+    // The completion gate keys its per-session baseline on this. Without it every
+    // Stop is refused for the wrong reason and no SessionStart ever records a
+    // baseline to refuse against.
+    const sessionId = typeof input.session_id === "string"
+        ? input.session_id
+        : undefined;
     if (input.hook_event_name === "SessionStart") {
-        return normalizeHookEvent({
-            event: "session-start",
-            projectRoot
-        });
+        return {
+            ...normalizeHookEvent({ event: "session-start", projectRoot }),
+            ...(sessionId === undefined ? {} : { sessionId })
+        };
     }
     if (input.hook_event_name === "Stop") {
-        return normalizeHookEvent({
+        // Claude publishes no termination reason: its Stop hook fires when the
+        // assistant has finished, which is agy's `model_stop`. The one distinction
+        // it does publish is recursion — a Stop the hook itself caused — and that
+        // is exactly the not-yet-idle case the gate lets through.
+        const stop = normalizeHookEvent({ event: "stop", projectRoot });
+        return {
             event: "stop",
-            projectRoot
-        });
+            projectRoot: stop.projectRoot,
+            ...(sessionId === undefined ? {} : { sessionId }),
+            terminationReason: "model_stop",
+            fullyIdle: input.stop_hook_active !== true
+        };
     }
     if (input.hook_event_name === "PreToolUse" &&
         input.tool_name === "Bash" &&

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

@@ -7,6 +7,30 @@ function json(value) {
 }
 export function claudeHookOutput(event, result) {
     const denialReason = result.remedy === undefined ? result.code : `${result.code}: ${result.remedy}`;
+    // The completion gate carries no verification evidence of its own — it reads
+    // evidence rather than producing it — so it never reaches the branch below
+    // and needs its own refusal.
+    if (event === "Stop" &&
+        result.action === "block" &&
+        result.code.startsWith("COMPLETION_GATE_")) {
+        return json({
+            decision: "block",
+            reason: `agent-ops: ${denialReason}`
+        });
+    }
+    if (event === "PreToolUse" &&
+        result.code === "COMPLETION_GATE_PERMIT_CONFIRMATION") {
+        // Asked, never allowed: a one-time Stop permit is the user's to grant, and
+        // an agent that could answer this for itself would hold the key to its own
+        // gate.
+        return json({
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "ask",
+                permissionDecisionReason: denialReason
+            }
+        });
+    }
     if (event === "Stop" && result.evidence !== undefined) {
         if (result.status === "FAIL") {
             const failed = result.evidence.commandResults