@kylecheng3146/agent-ops 0.1.24 → 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 ||

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>
@@ -55,6 +55,134 @@ Options:
   --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

@@ -52,8 +52,12 @@ export async function runHookCommand(options) {
         return descriptor.runtime.formatOutput(options.event, result);
     }
     catch {
-        if (options.harness === "agy" && options.event === "Stop" && 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

@@ -124,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);

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",
@@ -268,7 +272,7 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
         }
         const config = configOutcome.config;
         if (completionGateInstalled && !config.features.completionGate.enabled) {
-            writeHookOutput(io, harnessDescriptor("agy").runtime.formatOutput("Stop", {
+            writeHookOutput(io, harnessDescriptor(harness).runtime.formatOutput("Stop", {
                 action: "block",
                 status: "UNKNOWN",
                 code: "COMPLETION_GATE_CONFIG_DISABLED",
@@ -293,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,
@@ -320,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

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

@@ -133,7 +133,7 @@ export class CompletionGateService {
         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.")
+                ? gateResult("block", "UNKNOWN", "COMPLETION_GATE_SESSION_REQUIRED", "The host did not provide a session identifier; run doctor and use a one-time permit only after restoring hook input.")
                 : null;
         }
         if (event.event === "session-start") {

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

@@ -4,6 +4,7 @@ import { sha256 } from "../fs/hash.js";
 import { parseInstallManifest, PROJECT_MANIFEST_PATH } from "../fs/manifest.js";
 import { resolveContainedPath } from "../fs/paths.js";
 import { validateConfig } from "../schema/validate.js";
+import { BIND_DEPENDENT_TARGETS, detectHostRestriction } from "../review/host-sandbox.js";
 import { assertExpectedManagedBlock, assertSupportedManifestOwnership } from "./ownership.js";
 import { isOpencodeManagedPlugin } from "../adapters/opencode/config.js";
 import { harnessDescriptor, managedRules } from "./harness.js";
@@ -371,6 +372,49 @@ async function checkRegistrationDrift(root, manifest, config) {
         return check("registration-drift", "UNKNOWN", "Hook registration drift could not be assessed safely.", undefined, "No action needed; drift could not be computed.");
     }
 }
+/**
+ * Whether anything can ever be verified here. Completion requires current PASS
+ * evidence from a required verifier, so an empty list is not a light
+ * configuration — it is a loop that cannot close, and an installation reaches
+ * that state quietly whenever stack detection declines to guess.
+ */
+function checkVerificationCommands(config) {
+    if (config === undefined) {
+        return check("verification-commands", "UNKNOWN", "Configuration could not be read, so verifiers are unknown.");
+    }
+    if (config.verification.commands.length === 0) {
+        return check("verification-commands", "DEGRADED", "No verification command is configured, so no task can be completed.", 
+        // Codeless on purpose: the fix is an edit to the configuration file, not
+        // an agent-ops command, and a code here would force a non-zero exit on
+        // every installation whose stack detection declined to guess.
+        undefined, `Add verification.commands to ${CONFIG_PATH}, then run doctor again.`);
+    }
+    const required = config.verification.commands.filter(({ required: isRequired }) => isRequired);
+    if (required.length === 0) {
+        return check("verification-commands", "DEGRADED", "Every configured verification command is optional, so no criterion can " +
+            "be satisfied by one.", undefined, `Mark at least one command in ${CONFIG_PATH} as required.`);
+    }
+    return check("verification-commands", "PASS", `Required verifiers: ${required.map(({ id }) => id).join(", ")}.`);
+}
+/**
+ * What the surrounding host withholds from a reviewer. Reported separately
+ * from `review-targets` on purpose: a sandbox that blocks the network makes an
+ * authenticated CLI answer "not logged in", and reading that verdict as a
+ * credential problem is the misdiagnosis this check exists to prevent.
+ */
+async function checkHostSandbox(detect) {
+    const restriction = await (detect ?? detectHostRestriction)();
+    if (restriction === "network-blocked") {
+        return check("host-sandbox", "DEGRADED", "This process runs in a sandbox with no network access, so no review " +
+            "target can answer. Any authentication verdict below is unreliable.", undefined, "Run agent-ops outside the sandbox, or grant it escalated execution.");
+    }
+    if (restriction === "bind-blocked") {
+        return check("host-sandbox", "DEGRADED", `This process cannot open a loopback listener, so review targets that ` +
+            `need one (${BIND_DEPENDENT_TARGETS.join(", ")}) run last and may be ` +
+            "unable to answer.", undefined, "Run agent-ops outside the sandbox, or grant it escalated execution.");
+    }
+    return check("host-sandbox", "PASS", "No host sandbox restriction affects review targets.");
+}
 async function checkReviewTargets(config, probe, checkAuth) {
     const targets = config?.reviewRoles?.find((role) => role.role === "independent-review")?.targets ?? [];
     if (targets.length === 0) {
@@ -439,7 +483,9 @@ export async function doctorInstallation(options) {
             : []),
         await checkProbe("repository-trust", options.probes?.repositoryTrust),
         await checkProbe("smoke-availability", options.probes?.smokeAvailability),
-        await checkReviewTargets(config.config, options.probes?.reviewTarget, options.checkReviewTargetAuth === true)
+        await checkReviewTargets(config.config, options.probes?.reviewTarget, options.checkReviewTargetAuth === true),
+        await checkHostSandbox(options.probes?.hostRestriction),
+        checkVerificationCommands(config.config)
     ];
     return {
         checks,

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

@@ -308,7 +308,7 @@ export function managedRules(descriptor, context) {
         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("The completion gate runs on agy and Claude Code. It applies only when", "this conversation creates a Git-visible net change after its first", "session 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", "asks the user, 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/plan.js

@@ -65,11 +65,18 @@ function verificationCommandFromProposal(proposal) {
 async function detectVerificationCommands(root) {
     const discovery = await discoverProject(root);
     if (discovery.kind !== "project") {
-        return [];
+        return { commands: [], blockers: [discovery.message] };
     }
-    return discovery.proposals
+    const commands = discovery.proposals
         .filter((proposal) => proposal.confidence === "high")
         .map(verificationCommandFromProposal);
+    // What detection could not settle on its own. Kept even when commands were
+    // found, because an installation that ends with no verifier has to be able
+    // to say why: silence there leaves a loop that can never complete a task.
+    return {
+        commands,
+        blockers: discovery.decisions.map((decision) => `${decision.adapter}: ${decision.message}`)
+    };
 }
 function buildConfig(profiles, existing, reviewTargets = [], detectedCommands = [], completionGateEnabled = false) {
     // Absent reviewRoles means external review is disabled; an empty selection
@@ -130,11 +137,11 @@ async function planConfig(root, profiles, existingManifest, suppliedConfig, revi
         }
         existingConfig = result.value;
     }
-    const detectedCommands = existingConfig === undefined ||
+    const detected = existingConfig === undefined ||
         existingConfig.verification.commands.length === 0
         ? await detectVerificationCommands(root)
-        : [];
-    const config = buildConfig(profiles, existingConfig, reviewTargets, detectedCommands, completionGateEnabled);
+        : { commands: [], blockers: [] };
+    const config = buildConfig(profiles, existingConfig, reviewTargets, detected.commands, completionGateEnabled);
     const content = `${JSON.stringify(config, null, 2)}\n`;
     return {
         operation: {
@@ -150,7 +157,8 @@ async function planConfig(root, profiles, existingManifest, suppliedConfig, revi
             owner: "agent-ops"
         },
         config,
-        detectedVerification: detectedCommands
+        detectedVerification: detected.commands,
+        verificationBlockers: detected.blockers
     };
 }
 function pathKey(path) {
@@ -381,11 +389,16 @@ export async function createInstallPlan(options) {
     assertLoopProfileSupport(options.scope, options.harness, resolved.capabilities);
     const completionGateEnabled = options.existingConfig?.value.features.completionGate.enabled ??
         options.completionGateEnabled === true;
+    // agy and Claude Code are the hosts whose Stop hook can refuse a stop.
+    // codex never fires Stop under `codex exec` and rejects
+    // `permissionDecision:ask`, so its permit could not be user-approved;
+    // opencode's plugin can only deny a tool call.
+    const gateHosts = ["agy", "claude"];
     if (completionGateEnabled &&
         (options.scope !== "project" ||
-            !options.harness.includes("agy") ||
+            !gateHosts.some((host) => options.harness.includes(host)) ||
             !resolved.capabilities.includes("project-loop"))) {
-        throw new AgentOpsError("COMPLETION_GATE_UNSUPPORTED", "The completion gate requires project scope with the agy harness and loop profile.");
+        throw new AgentOpsError("COMPLETION_GATE_UNSUPPORTED", "The completion gate requires project scope with the agy or claude harness and loop profile.");
     }
     if (completionGateEnabled &&
         !resolved.capabilities.includes("completion-gate")) {
@@ -589,6 +602,7 @@ export async function createInstallPlan(options) {
         config: config.config,
         manifest,
         operations,
-        detectedVerification: config.detectedVerification
+        detectedVerification: config.detectedVerification,
+        verificationBlockers: config.verificationBlockers
     };
 }

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

@@ -7,6 +7,23 @@ export function agyVersionSupported(versionOutput) {
     return version !== undefined && !version.some((part, index) => part < MINIMUM_AGY_VERSION[index] &&
         version.slice(0, index).every((prior, priorIndex) => prior === MINIMUM_AGY_VERSION[priorIndex]));
 }
+/**
+ * Whether a loaded hook command is the managed handler for this event. The
+ * event and the ownership marker are both required, but flags may sit between
+ * them: the Stop handler carries `--completion-gate` when the project loop is
+ * enabled, and matching the whole tail as one string reported every gated
+ * installation as unmanaged — a failure `agent-ops update` could never fix,
+ * because update installs exactly the command being rejected.
+ */
+function isManagedHookCommand(command, event) {
+    const marker = " --managed-by=agent-ops";
+    if (!command.endsWith(marker)) {
+        return false;
+    }
+    const flags = command.slice(0, -marker.length);
+    return flags.endsWith(` agy ${event}`) ||
+        flags.includes(` agy ${event} --`);
+}
 export function agyRuntimeStatus(versionOutput, hooksOutput, expectedEvents = []) {
     const match = /\b(\d+)\.(\d+)\.(\d+)\b/u.exec(versionOutput);
     if (!agyVersionSupported(versionOutput)) {
@@ -35,7 +52,7 @@ export function agyRuntimeStatus(versionOutput, hooksOutput, expectedEvents = []
                 return (typeof action === "object" && action !== null && !Array.isArray(action) &&
                     action.event === nativeEvent &&
                     typeof action.command === "string" &&
-                    action.command.endsWith(` agy ${expected} --managed-by=agent-ops`));
+                    isManagedHookCommand(action.command, expected));
             }));
         });
         if (!Array.isArray(hooks) || (expectedEvents.length > 0 && !loaded)) {

package/dist/runtime/src/review/execute.js

@@ -1,4 +1,4 @@
-import { chmod, copyFile, lstat, mkdir, mkdtemp, realpath, rm } from "node:fs/promises";
+import { chmod, copyFile, lstat, mkdir, mkdtemp, realpath, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { runVerificationCommand } from "../verify/spawn.js";
@@ -7,6 +7,7 @@ import { extractReviewObject } from "./extract.js";
 import { buildTargetInvocation } from "./invocation.js";
 import { reviewReportResults, reviewReportStatus, validateReviewReport } from "./report.js";
 import { detectHostTarget, orderChain } from "./roles.js";
+import { BIND_DEPENDENT_TARGETS, detectHostRestriction } from "./host-sandbox.js";
 import { buildAdversarialPrompt, buildReviewPrompt } from "./runner.js";
 /**
  * Full repository reviews need far more headroom than the lightweight auth
@@ -15,6 +16,15 @@ import { buildAdversarialPrompt, buildReviewPrompt } from "./runner.js";
  * review while looking like an unavailable target.
  */
 export const DEFAULT_REVIEW_TIMEOUT_MS = 900_000;
+/**
+ * How long a reviewer may produce nothing at all before it is treated as
+ * wedged rather than slow. A reviewer the host sandbox has blocked never
+ * writes another byte, and waiting out the full review timeout spends 15
+ * minutes per target — 45 for a three-target chain — to learn that. Progress
+ * output and a growing log file both count, so a reviewer that is merely
+ * thinking hard is never cut off.
+ */
+export const DEFAULT_STALL_IDLE_MS = 90_000;
 export class ReviewInterruptedError extends Error {
     signal;
     constructor(signal) {
@@ -121,6 +131,54 @@ function rejectedCallReason(output) {
     }
     return "capability-unavailable";
 }
+/**
+ * Watches one reviewer for silence. Two things count as a sign of life: a byte
+ * on either stream, reported through `beat`, and growth of the target's own log
+ * file, polled here because a target that buffers stdout until it answers has
+ * no other observable heartbeat.
+ */
+function watchForStall(logFile, parent, idleMs) {
+    const controller = new AbortController();
+    const pollMs = Math.max(20, Math.min(5_000, Math.floor(idleMs / 3)));
+    let lastBeat = Date.now();
+    let logSize = -1;
+    let stalled = false;
+    const beat = () => {
+        lastBeat = Date.now();
+    };
+    const check = async () => {
+        if (logFile !== undefined) {
+            try {
+                const info = await stat(logFile);
+                if (info.size > logSize) {
+                    logSize = info.size;
+                    beat();
+                }
+            }
+            catch {
+                // The target has not created its log yet, which is not a heartbeat.
+            }
+        }
+        if (!stalled && Date.now() - lastBeat >= idleMs) {
+            stalled = true;
+            controller.abort("stalled");
+        }
+    };
+    const timer = setInterval(() => {
+        void check();
+    }, pollMs);
+    timer.unref();
+    return {
+        signal: parent === undefined
+            ? controller.signal
+            : AbortSignal.any([parent, controller.signal]),
+        stalled: () => stalled,
+        beat,
+        stop: () => {
+            clearInterval(timer);
+        }
+    };
+}
 function throwIfInterrupted(target, options, failureClass) {
     if (failureClass !== "aborted" && options.signal?.aborted !== true) {
         return;
@@ -187,13 +245,14 @@ async function attemptTarget(request, options) {
     });
     const attemptDirectory = await mkdtemp(join(tmpdir(), "agent-ops-review-"));
     try {
+        const agyLog = target === "agy"
+            ? join(attemptDirectory, "agy.log")
+            : undefined;
         const invocationRequest = {
             target,
             prompt: request.prompt,
             repositoryRoot: request.repositoryRoot,
-            ...(target === "agy"
-                ? { logFile: join(attemptDirectory, "agy.log") }
-                : {}),
+            ...(agyLog === undefined ? {} : { logFile: agyLog }),
             ...(options.model === undefined ? {} : { model: options.model }),
             ...(options.effort === undefined ? {} : { effort: options.effort })
         };
@@ -237,6 +296,14 @@ async function attemptTarget(request, options) {
                     : firstComplaint(capability.stderr, capability.stdout) ??
                         `help probe failed (${capability.failureClass})`, "skipping");
         }
+        // agy takes its log file unconditionally; claude's equivalent is passed
+        // only when this install advertises it, so an older CLI keeps reviewing
+        // and merely loses the file heartbeat.
+        const heartbeatLog = target === "agy"
+            ? agyLog
+            : target === "claude" && help.includes("--debug-file")
+                ? join(attemptDirectory, "claude-debug.log")
+                : undefined;
         const snapshotRoot = join(attemptDirectory, "repository");
         const snapshotError = await snapshotRepository(request, snapshotRoot, options);
         if (snapshotError !== undefined) {
@@ -251,10 +318,20 @@ async function attemptTarget(request, options) {
                         "Run every repository-relative inspection in that directory.",
                         "For terminal commands, use only git status, git diff, git log, or git show; " +
                             "read specific files with file-reading tools instead of ls, find, cat, or rg.",
+                        // agy's only read-only mode is plan mode, and plan mode's default
+                        // job is to author an implementation plan and then ask the caller
+                        // whether to proceed. Under `--print` that question ends the one
+                        // turn it gets, so the review comes back empty after minutes of
+                        // work. Saying what the turn is for is what keeps it answering.
+                        "You are answering a review question, not planning work. Do not write " +
+                            "an implementation plan. Do not create or edit any file. Do not ask " +
+                            "the user anything. Reply with the JSON object the schema requires " +
+                            "and nothing else.",
                         request.prompt
                     ].join("\n")
                 }
                 : {}),
+            ...(heartbeatLog === undefined ? {} : { logFile: heartbeatLog }),
             repositoryRoot: snapshotRoot
         });
         executionDirectory = snapshotRoot;
@@ -263,25 +340,42 @@ async function attemptTarget(request, options) {
         }
         throwIfInterrupted(target, options);
         options.onProgress?.(`${target}: review started (timeout: ${Math.ceil((options.timeoutMs ?? DEFAULT_REVIEW_TIMEOUT_MS) / 1_000)}s)`);
-        const spawned = await runVerificationCommand({
-            id: `review-${request.label}`,
-            command: invocation.command,
-            args: [...invocation.args],
-            cwd: executionDirectory,
-            required: true,
-            evidence: { kind: "exit-code" },
-            timeoutMs: options.timeoutMs ?? DEFAULT_REVIEW_TIMEOUT_MS
-        }, {
-            cwd: executionDirectory,
-            ...(options.runner === undefined ? {} : { runner: options.runner }),
-            ...(options.outputLimitBytes === undefined
-                ? {}
-                : { outputLimitBytes: options.outputLimitBytes }),
-            stdin: invocation.stdin,
-            env: environment,
-            replaceEnv: true,
-            ...(options.signal === undefined ? {} : { signal: options.signal })
-        });
+        const stallIdleMs = options.stallIdleMs ?? DEFAULT_STALL_IDLE_MS;
+        const stallWatch = watchForStall(heartbeatLog, options.signal, stallIdleMs);
+        let spawned;
+        try {
+            spawned = await runVerificationCommand({
+                id: `review-${request.label}`,
+                command: invocation.command,
+                args: [...invocation.args],
+                cwd: executionDirectory,
+                required: true,
+                evidence: { kind: "exit-code" },
+                timeoutMs: options.timeoutMs ?? DEFAULT_REVIEW_TIMEOUT_MS
+            }, {
+                cwd: executionDirectory,
+                ...(options.runner === undefined ? {} : { runner: options.runner }),
+                ...(options.outputLimitBytes === undefined
+                    ? {}
+                    : { outputLimitBytes: options.outputLimitBytes }),
+                stdin: invocation.stdin,
+                env: environment,
+                replaceEnv: true,
+                signal: stallWatch.signal,
+                onActivity: stallWatch.beat
+            });
+        }
+        finally {
+            stallWatch.stop();
+        }
+        // Ahead of `throwIfInterrupted`, which reads the same `aborted` failure
+        // class as a user interrupt. A stall is this executor's own abort, and
+        // ends one target rather than the whole review.
+        if (stallWatch.stalled() && options.signal?.aborted !== true) {
+            return skip("stalled", `no output for ${Math.max(1, Math.round(stallIdleMs / 1_000))}s; the reviewer is ` +
+                "probably blocked by the host sandbox, and retrying with more " +
+                "permission will not help");
+        }
         throwIfInterrupted(target, options, spawned.failureClass);
         if (spawned.failureClass === "timeout") {
             return skip("timeout", "the reviewer exceeded its timeout");
@@ -345,8 +439,38 @@ async function attemptTarget(request, options) {
 export function createReviewExecutor(options) {
     const report = options.onProgress ?? (() => { });
     const host = detectHostTarget(options.env ?? process.env);
-    const chain = orderChain(options.targets, host);
+    const ordered = orderChain(options.targets, host);
     return async (request) => {
+        // Asked before anything is spent. A reviewer inherits this process's
+        // sandbox, so a restriction found here is a restriction every target in
+        // the chain would hit — one at a time, minutes apart.
+        const restriction = await detectHostRestriction({
+            env: options.env ?? process.env,
+            ...(options.probeBind === undefined ? {} : { probeBind: options.probeBind })
+        });
+        if (restriction === "network-blocked") {
+            report("host: the sandbox around this process blocks network access, so no " +
+                "reviewer can answer → not running the chain");
+            return {
+                status: "NOT_RUN",
+                reason: "host-sandboxed",
+                ...(host === undefined ? {} : { harness: host }),
+                attempts: []
+            };
+        }
+        // Only agy needs a loopback listener, so a bind-blocked host is not a dead
+        // end — it is a reason to spend the other targets first rather than
+        // discovering the same failure at the head of the chain every time.
+        const chain = restriction === "bind-blocked"
+            ? [
+                ...ordered.filter((target) => !BIND_DEPENDENT_TARGETS.includes(target)),
+                ...ordered.filter((target) => BIND_DEPENDENT_TARGETS.includes(target))
+            ]
+            : ordered;
+        if (restriction === "bind-blocked" && chain.join() !== ordered.join()) {
+            report("host: this process cannot open a loopback listener, so targets that " +
+                `need one run last (chain: ${chain.join(" → ")})`);
+        }
         const expectedCriterionIds = request.invocation.packet.criteria.map((criterion) => criterion.id);
         const repositoryRoot = await realpath(options.cwd);
         const shared = {

package/dist/runtime/src/review/host-sandbox.js

@@ -0,0 +1,49 @@
+import { createServer } from "node:net";
+/** Targets that need a loopback listener of their own to answer at all. */
+export const BIND_DEPENDENT_TARGETS = ["agy"];
+const BIND_PROBE_TIMEOUT_MS = 2_000;
+/**
+ * Opens and immediately closes a loopback listener on an ephemeral port.
+ * Cheap enough to run before every review, and it exercises exactly the
+ * capability a sandboxed host withholds.
+ */
+export async function probeLoopbackBind() {
+    return await new Promise((resolve) => {
+        const server = createServer();
+        let settled = false;
+        const finish = (value) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            server.close(() => resolve(value));
+        };
+        const timer = setTimeout(() => finish(false), BIND_PROBE_TIMEOUT_MS);
+        timer.unref();
+        server.once("error", () => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                resolve(false);
+            }
+        });
+        server.listen(0, "127.0.0.1", () => finish(true));
+    });
+}
+/**
+ * The host's restriction, read from what the host publishes about itself and
+ * then, when that says nothing, from what this process can actually do. Codex
+ * declares both facts in the environment; nothing else does, so the probe is
+ * what covers every other host.
+ */
+export async function detectHostRestriction(options = {}) {
+    const env = options.env ?? process.env;
+    // Declared and total: no reviewer can reach its own API, so probing the
+    // narrower loopback capability would only add latency to a settled answer.
+    if (env.CODEX_SANDBOX_NETWORK_DISABLED === "1") {
+        return "network-blocked";
+    }
+    const probe = options.probeBind ?? probeLoopbackBind;
+    return (await probe()) ? "none" : "bind-blocked";
+}

package/dist/runtime/src/review/invocation.js

@@ -66,6 +66,23 @@ export const READ_ONLY_ARGS = {
     claude: ["--permission-mode", "plan"],
     codex: ["-s", "read-only"]
 };
+/**
+ * Where a target writes its running log, when it has one. This is the only
+ * heartbeat available for a target whose stdout stays silent until the answer
+ * arrives: the file grows while the reviewer works, and stops growing when it
+ * is wedged. claude's flag is passed opportunistically by the caller, so an
+ * install that predates `--debug-file` still reviews — it only loses the
+ * heartbeat.
+ */
+function logArgs(target, logFile) {
+    if (logFile === undefined) {
+        return [];
+    }
+    if (target === "agy") {
+        return ["--log-file", logFile];
+    }
+    return target === "claude" ? ["--debug-file", logFile] : [];
+}
 /** Per-target customization suppression. */
 function isolationArgs(target) {
     return target === "claude"
@@ -131,9 +148,7 @@ export function buildTargetInvocation(request) {
             ...(request.repositoryRoot === undefined
                 ? []
                 : ["--add-dir", request.repositoryRoot]),
-            ...(request.target !== "agy" || request.logFile === undefined
-                ? []
-                : ["--log-file", request.logFile]),
+            ...logArgs(request.target, request.logFile),
             ...isolationArgs(request.target),
             ...shared
         ],

package/dist/runtime/src/review/render.js

@@ -51,6 +51,20 @@ export function renderReviewResult(result) {
             result.attempts?.some((attempt) => attempt.reason === "login-required")) {
             lines.push("Run: agent-ops doctor --check-auth to verify target authentication.");
         }
+        if (result.reason === "host-sandboxed") {
+            lines.push("No target ran: the sandbox around this process blocks the network a " +
+                "reviewer needs. Run agent-ops review outside the sandbox, or grant " +
+                "this command escalated execution and run it again.");
+        }
+        // Deliberately not the authentication line: a stalled reviewer started and
+        // then went silent, so re-running it with more permission only spends the
+        // same wait again.
+        if (result.reason === "stalled" ||
+            result.attempts?.some((attempt) => attempt.reason === "stalled")) {
+            lines.push("A stalled reviewer is usually blocked by the host sandbox. Escalating " +
+                "permission and retrying does not help; run agent-ops review outside " +
+                "the sandbox instead.");
+        }
         return `${lines.join("\n")}\n`;
     }
     const report = result.report;

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

@@ -207,7 +207,12 @@ export class TaskService {
         if (current.status === "archived") {
             throw taskError("TASK_NOT_ACTIVE", "An archived task cannot be completed.");
         }
-        const submitted = normalizeEvidence(current.task, evidenceInput);
+        // Supplying nothing means "the evidence this task already carries".
+        // Re-typing it changes no outcome — the union below adds the recorded
+        // references to whatever was submitted, so evidence can never be dropped
+        // by naming less of it — and forcing a caller to copy references back out
+        // of the task store buys nothing but the chance to mistype them.
+        const submitted = normalizeEvidence(current.task, Object.keys(evidenceInput).length === 0 ? current.evidence : evidenceInput);
         // A caller cannot hide a recorded failure by submitting only older PASS references.
         const evidence = normalizeEvidence(current.task, Object.fromEntries(Object.entries(submitted).map(([criterionId, references]) => [criterionId,
             [...new Set([...(current.evidence[criterionId] ?? []), ...references])]])));

package/dist/runtime/src/verify/spawn.js

@@ -45,7 +45,7 @@ async function* readableBytes(stream) {
  * last, and its failure list just before it, so head-truncating a large run
  * discards exactly the part that carries the evidence.
  */
-async function captureOutput(stream, limit) {
+async function captureOutput(stream, limit, onActivity) {
     const chunks = [];
     let storedBytes = 0;
     let truncated = false;
@@ -72,6 +72,7 @@ async function captureOutput(stream, limit) {
     try {
         for await (const value of stream) {
             retain(Buffer.from(value));
+            onActivity?.();
         }
     }
     catch {
@@ -295,8 +296,8 @@ export async function runVerificationCommand(command, options) {
     catch {
         return emptyResult(command.id, "spawn-failed", elapsedMilliseconds(startedAt, now()));
     }
-    const stdout = captureOutput(running.stdout, outputLimit);
-    const stderr = captureOutput(running.stderr, outputLimit);
+    const stdout = captureOutput(running.stdout, outputLimit, options.onActivity);
+    const stderr = captureOutput(running.stderr, outputLimit, options.onActivity);
     let timer;
     const timeout = new Promise((resolve) => {
         timer = setTimeout(() => resolve({ kind: "timeout" }), timeoutMs);

package/docs/en/guides/configuration.md

@@ -161,17 +161,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
+For `agy` or `claude` plus `loop`, the interactive installer recommends
 `features.completionGate.enabled`; non-interactive installs require the explicit
-`--completion-gate` flag. The gate uses the documented `conversationId`,
+`--completion-gate` flag. These are the two hosts whose Stop hook can refuse a
+stop: codex never fires its Stop hook under `codex exec` and rejects
+`permissionDecision: ask`, so its permit could not be user-approved, and
+OpenCode's plugin can only deny a tool call. 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.
+error stops, max-step stops, and non-idle stops continue normally. Claude Code
+enforces the same gate through its own Stop contract, answering a refusal with
+`decision: "block"`. It does not change Codex 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>`, guarded by
+agy's documented `force_ask` decision and by Claude's `permissionDecision: ask`.
 
 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/).
@@ -213,8 +217,8 @@ classified invalid installed configuration. The managed OpenCode
 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 ordinary Stop verification
-failure paths stay fail-open. Only the explicitly enabled agy completion gate
-fails closed at final Stop.
+failure paths stay fail-open. Only the explicitly enabled completion gate fails
+closed at final Stop, on agy and Claude Code.
 
 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

package/docs/zh-TW/guides/configuration.md

@@ -143,16 +143,19 @@ agy 會安裝原生 `PreInvocation` 與 `PreToolUse(run_command)` 子集，docto
 位於 `.gemini/config/hooks.json`；user scope 會修改共享 Gemini rule surface
 `.gemini/GEMINI.md`。機器可讀的 `/hooks` 診斷要求 agy 1.1.12 以上。
 
-`agy` 搭配 `loop` 時，互動式 installer 會建議啟用
+`agy` 或 `claude` 搭配 `loop` 時，互動式 installer 會建議啟用
 `features.completionGate.enabled`；非互動安裝必須明確傳入
-`--completion-gate`。閘門使用官方定義的 `conversationId`、
+`--completion-gate`。這兩者是 Stop hook 能真正拒絕收工的 host：codex 在
+`codex exec` 下不會觸發 Stop hook，且拒絕 `permissionDecision: ask`，其 permit
+無法交由使用者核准；OpenCode plugin 只能拒絕單一 tool call。閘門使用官方定義的 `conversationId`、
 `terminationReason` 與 `fullyIdle` Stop 欄位，只有在本次 conversation 產生
 Git-visible net change 且缺少當前 task、驗證或 review 證據時，才回傳官方定義的
 `decision: "continue"`。純問答、分析、唯讀診斷、錯誤、max-step 與 non-idle Stop
-都正常結束；本版不改變 Codex、Claude Code 或 OpenCode 的 Stop 行為。Headless
+都正常結束。Claude Code 以自身的 Stop contract 執行同一道閘門，拒絕時回傳
+`decision: "block"`；本版不改變 Codex 或 OpenCode 的 Stop 行為。Headless
 請使用 `agent-ops agy-run -- <agy arguments>`；使用者可核准一次
-`agent-ops allow-stop --session <conversationId>`，該命令由官方定義的
-`force_ask` 強制詢問。
+`agent-ops allow-stop --session <conversationId>`，該命令在 agy 由官方定義的
+`force_ask` 強制詢問，在 Claude Code 則由 `permissionDecision: ask` 強制詢問。
 
 官方依據：[agy CLI workspace rule file](https://www.antigravity.google/docs/cli/best-practices/)
 與 [Antigravity hook contract](https://www.antigravity.google/docs/hooks/)。
@@ -191,7 +194,8 @@ OpenCode `tool.execute.before` plugin 可在其支援的 Bash surface
 上 throw 文件化的 command-policy denial 或 unavailable-runtime error。Codex 明確
 不執行強制措施（`unknown`）。這些是 agent-ops 的 output 與 plugin contract，不
 證明 host 會實際遵守 denial。所有 `SessionStart` 與一般 Stop verification failure
-path 都維持 fail-open；只有明確啟用的 agy completion gate 會在 final Stop fail-closed。
+path 都維持 fail-open；只有明確啟用的 completion gate 會在 final Stop
+fail-closed，適用於 agy 與 Claude Code。
 
 Claude 的無效 config fallback 有四項防護：(1) 缺少 project configuration 時保持
 fail-open，因此只有無效的 `.agent-ops/config.json` 能進入 fallback；(2) manifest

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kylecheng3146/agent-ops",
-  "version": "0.1.24",
+  "version": "0.2.0",
   "description": "Evidence-driven development loops for agy, Codex, Claude Code, and opencode",
   "type": "module",
   "license": "MIT",