@kylecheng3146/agent-ops 0.1.24 → 0.2.1

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

@@ -3,6 +3,16 @@ import { safeTaskText } from "../task/render.js";
 function safe(value) {
     return safeTaskText(redactSecrets(value));
 }
+/**
+ * NOT_RUN reasons that mean the task's verification evidence, not the reviewer,
+ * stopped the run: every one of them is cleared by producing fresh evidence.
+ */
+const VERIFICATION_EVIDENCE_REASONS = new Set([
+    "stale-verification",
+    "missing-verification-evidence",
+    "unreadable-verification-evidence",
+    "verification-not-passed"
+]);
 function lineList(values) {
     return values.length === 0 ? ["- none"] : values.map((value) => `- ${safe(value)}`);
 }
@@ -51,6 +61,40 @@ export function renderReviewResult(result) {
             result.attempts?.some((attempt) => attempt.reason === "login-required")) {
             lines.push("Run: agent-ops doctor --check-auth to verify target authentication.");
         }
+        // Evidence is pinned to the source it was produced from, so any edit to a
+        // changed file after the verifier ran — a doc rewritten by a later step
+        // counts — voids it. Without the next command the caller reads
+        // "stale-verification" as a review failure and retries review instead.
+        if (result.reason === "stale-verification") {
+            lines.push("The source changed after this evidence was recorded, so it no longer " +
+                "describes the worktree under review.");
+        }
+        const verifyCommand = `agent-ops verify --task ${result.taskId ?? "<task-id>"}`;
+        if (result.reason === "verification-not-passed") {
+            // No review invitation: the verifier failed, and review is refused until
+            // a passing run replaces that evidence. Naming review here is what sent
+            // the caller back to the command that had just refused them.
+            lines.push("The recorded verification did not pass. Fix what failed, then run: " +
+                `${verifyCommand}. Re-running review cannot turn a failing verifier ` +
+                "into a PASS.");
+        }
+        else if (VERIFICATION_EVIDENCE_REASONS.has(result.reason ?? "")) {
+            lines.push(`Run: ${verifyCommand}, then run this review again.`);
+        }
+        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.1",
   "description": "Evidence-driven development loops for agy, Codex, Claude Code, and opencode",
   "type": "module",
   "license": "MIT",