@kylecheng3146/agent-ops 0.1.22 → 0.2.0

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/security/trust.js

@@ -188,8 +188,7 @@ export class FileTrustStore {
         }
         await withPrivateFileLock(this.#path, this.#anchorDirectory, async () => {
             const store = await this.#read();
-            const records = store.records.filter((record) => record.binding.canonicalPath !== binding.canonicalPath &&
-                record.binding.remoteIdentity !== binding.remoteIdentity);
+            const records = store.records.filter((record) => record.binding.canonicalPath !== binding.canonicalPath);
             records.push({ binding: structuredClone(binding), grantedAt });
             await this.#write({ schemaVersion: 1, records });
         });

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

@@ -0,0 +1,62 @@
+import { calculateConfigHash } from "../config/hash.js";
+import { findReviewAttestation } from "../review/attestation.js";
+import { validateEvidence, validateTaskAgainstConfig } from "../schema/validate.js";
+import { isPassingVerificationEvidence } from "../verify/evidence.js";
+export async function checkTaskCompletionEvidence(stored, options) {
+    const { root, config, sourceFingerprint, evidenceStore } = options;
+    if (stored.failureFingerprint !== null) {
+        return { status: "FAIL", code: "VERIFICATION_FAILED", remedy: "Resolve the latest verification failure before completing the task." };
+    }
+    const configHash = calculateConfigHash(config);
+    if (!validateTaskAgainstConfig(stored.task, config).ok || stored.policyConfigHash !== configHash) {
+        return { status: "FAIL", code: "TASK_STALE", remedy: "Recreate the task against the current config, then verify and review it." };
+    }
+    for (const criterion of stored.task.criteria) {
+        const commands = config.verification.commands.filter(({ id, required }) => criterion.verifierIds.includes(id) && required);
+        if (commands.length === 0) {
+            return { status: "FAIL", code: "REQUIRED_VERIFIER_MISSING", remedy: "Configure a required verifier for every criterion, then recreate, verify and review the task." };
+        }
+        for (const command of commands) {
+            let latest;
+            for (const reference of stored.evidence[criterion.id] ?? []) {
+                if (reference.startsWith("review:"))
+                    continue;
+                const validation = validateEvidence(await evidenceStore.load(reference));
+                if (!validation.ok)
+                    continue;
+                const evidence = validation.value;
+                if (evidence.taskId === stored.task.id && evidence.criterionId === criterion.id &&
+                    evidence.commandId === command.id && evidence.configHash === configHash &&
+                    evidence.sourceFingerprint === sourceFingerprint &&
+                    (latest === undefined || Date.parse(evidence.finishedAt) > Date.parse(latest.finishedAt) ||
+                        (Date.parse(evidence.finishedAt) === Date.parse(latest.finishedAt) && !isPassingVerificationEvidence(command, evidence)))) {
+                    latest = evidence;
+                }
+            }
+            if (latest === undefined || !isPassingVerificationEvidence(command, latest)) {
+                return { status: "FAIL", code: "EVIDENCE_REQUIRED", remedy: "Run agent-ops verify and supply current PASS evidence for every required verifier." };
+            }
+        }
+    }
+    const attestation = await findReviewAttestation(root, sourceFingerprint);
+    if (attestation === null || attestation.taskId !== stored.task.id) {
+        return { status: "FAIL", code: "REVIEW_REQUIRED", remedy: "Run agent-ops review --yes for the whole task and current source." };
+    }
+    return null;
+}
+/** Include descendants so legacy completed children cannot hide unfinished work. */
+export function findIncompleteSubtask(records, taskId) {
+    const descendants = new Set([taskId]);
+    let previousSize = 0;
+    while (previousSize !== descendants.size) {
+        previousSize = descendants.size;
+        for (const record of records) {
+            if (record.task.parentTaskId !== undefined && descendants.has(record.task.parentTaskId)) {
+                descendants.add(record.task.id);
+                if (record.status === "active" || record.completedAt === null || record.failureFingerprint !== null)
+                    return record;
+            }
+        }
+    }
+    return undefined;
+}

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

@@ -1,8 +1,12 @@
 import { randomUUID } from "node:crypto";
 import { TASK_SCHEMA_VERSION } from "../contracts.js";
 import { AgentOpsError } from "../fs/paths.js";
-import { validateTask } from "../schema/validate.js";
+import { validateEvidence, validateTask } from "../schema/validate.js";
 import { renderTaskMarkdown } from "./render.js";
+import { checkTaskCompletionEvidence, findIncompleteSubtask } from "./completion.js";
+import { calculateConfigHash, FileEvidenceStore } from "../verify/evidence.js";
+import { resolveReviewScope } from "../review/scope.js";
+import { calculateSourceFingerprint } from "../verify/source-fingerprint.js";
 import { advanceFailureFingerprint } from "../verify/fingerprint.js";
 const SESSION_ID_PATTERN = /^[^\0\r\n]{1,256}$/u;
 function defaultTaskId() {
@@ -67,10 +71,12 @@ export class TaskService {
     #store;
     #generateId;
     #now;
+    #completion;
     constructor(store, options = {}) {
         this.#store = store;
         this.#generateId = options.generateId ?? defaultTaskId;
         this.#now = options.now ?? (() => new Date().toISOString());
+        this.#completion = options.completion;
     }
     async create(input) {
         if (input.policyConfigHash !== undefined &&
@@ -105,8 +111,8 @@ export class TaskService {
                 if (parent === undefined) {
                     throw taskError("TASK_PARENT_NOT_FOUND", `Parent task not found: ${input.parentTaskId}`);
                 }
-                if (parent.status === "archived") {
-                    throw taskError("TASK_PARENT_NOT_ACTIVE", "An archived task cannot take new subtasks.");
+                if (parent.status !== "active") {
+                    throw taskError("TASK_PARENT_NOT_ACTIVE", "Only an active task can take new subtasks.");
                 }
             }
             const record = {
@@ -196,12 +202,75 @@ export class TaskService {
     }
     async complete(taskId, evidenceInput) {
         const now = assertTimestamp(this.#now());
+        const snapshot = await this.#store.read();
+        const current = findTask(snapshot, taskId);
+        if (current.status === "archived") {
+            throw taskError("TASK_NOT_ACTIVE", "An archived task cannot be completed.");
+        }
+        // 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])]])));
+        const unfinished = findIncompleteSubtask(snapshot.tasks, taskId);
+        if (unfinished !== undefined) {
+            throw taskError("TASK_SUBTASK_INCOMPLETE", `Complete subtask ${unfinished.task.id} before its parent; archiving unfinished work does not satisfy completion.`);
+        }
+        const completion = this.#completion;
+        if (completion === undefined) {
+            throw taskError("TASK_COMPLETION_UNAVAILABLE", "Task completion requires repository config, source, verification evidence and review validation.");
+        }
+        const evidenceStore = new FileEvidenceStore(completion.root, completion.root);
+        for (const [criterionId, references] of Object.entries(evidence)) {
+            for (const reference of references) {
+                if (reference.startsWith("review:") && current.evidence[criterionId]?.includes(reference))
+                    continue;
+                const validation = validateEvidence(await evidenceStore.load(reference));
+                if (!validation.ok || validation.value.taskId !== taskId || validation.value.criterionId !== criterionId) {
+                    throw taskError("TASK_EVIDENCE_INVALID", `Criterion ${criterionId} requires resolvable evidence belonging to this task and criterion.`);
+                }
+            }
+        }
+        const fingerprint = async () => {
+            try {
+                const scope = await resolveReviewScope({ root: completion.root, runner: completion.gitRunner,
+                    ...(completion.base === undefined ? {} : { base: completion.base }) });
+                return await calculateSourceFingerprint(completion.root, scope, completion.gitRunner);
+            }
+            catch (error) {
+                if (error instanceof AgentOpsError && error.code === "REVIEW_NO_CHANGE_SURFACE") {
+                    throw taskError("TASK_COMPLETION_SCOPE_REQUIRED", completion.base === undefined
+                        ? "No changed worktree scope. For committed work, run verify, review and task complete with the same --base <git-ref>."
+                        : "The requested base range has no changed paths; choose a base that precedes the committed work.");
+                }
+                throw error;
+            }
+        };
+        const config = await completion.loadConfig();
+        const sourceFingerprint = await fingerprint();
+        const problem = await checkTaskCompletionEvidence({ ...current, evidence }, {
+            root: completion.root, config, sourceFingerprint,
+            evidenceStore
+        });
+        if (problem !== null) {
+            throw taskError(`TASK_COMPLETION_${problem.code}`, problem.remedy);
+        }
+        if (sourceFingerprint !== await fingerprint() ||
+            calculateConfigHash(config) !== calculateConfigHash(await completion.loadConfig())) {
+            throw taskError("TASK_COMPLETION_SOURCE_CHANGED", "Source or config changed during completion; verify and review again.");
+        }
         return await this.#store.mutate((state) => {
-            const current = findTask(state, taskId);
-            if (current.status === "archived") {
-                throw taskError("TASK_NOT_ACTIVE", "An archived task cannot be completed.");
+            if (JSON.stringify(findTask(state, taskId)) !== JSON.stringify(current)) {
+                throw taskError("TASK_COMPLETION_STATE_CHANGED", "Task changed during completion; retry against its current evidence and status.");
+            }
+            const unfinished = findIncompleteSubtask(state.tasks, taskId);
+            if (unfinished !== undefined) {
+                throw taskError("TASK_SUBTASK_INCOMPLETE", `Complete subtask ${unfinished.task.id} before its parent; archiving unfinished work does not satisfy completion.`);
             }
-            const evidence = normalizeEvidence(current.task, evidenceInput);
             if (current.status === "complete") {
                 if (JSON.stringify(current.evidence) !== JSON.stringify(evidence)) {
                     throw taskError("TASK_ALREADY_COMPLETE", "Completed task evidence cannot be replaced.");

package/dist/runtime/src/verify/change-surface.js

@@ -60,6 +60,9 @@ async function collectPaths(runner, args) {
     return parseNulPaths(result.stdout);
 }
 export async function collectChangeSurface(runner) {
+    const trackedRuntime = await collectPaths(runner, [
+        "ls-files", "--cached", "-z", "--", ".agent-ops/tasks/", ".agent-ops/reviews/"
+    ]);
     const staged = await collectPaths(runner, [
         "diff",
         "--cached",
@@ -69,6 +72,9 @@ export async function collectChangeSurface(runner) {
         "--no-textconv",
         "-z"
     ]);
+    if (trackedRuntime.length > 0 || staged.some((path) => path.startsWith(".agent-ops/tasks/") || path.startsWith(".agent-ops/reviews/"))) {
+        throw new AgentOpsError("CHANGE_SURFACE_TRACKED_RUNTIME", "Runtime output is staged or tracked under .agent-ops/tasks/ or .agent-ops/reviews/. Move any source files out of these runtime directories, add ignore rules (agent-ops update), then remove runtime files from the Git index with git rm -r --cached --ignore-unmatch -- .agent-ops/tasks/ .agent-ops/reviews/; keep local files, commit any staged runtime removals, then rerun verify/review.");
+    }
     const unstaged = await collectPaths(runner, [
         "diff",
         "--name-only",
@@ -77,12 +83,15 @@ export async function collectChangeSurface(runner) {
         "--no-textconv",
         "-z"
     ]);
-    const untracked = await collectPaths(runner, [
+    const untracked = (await collectPaths(runner, [
         "ls-files",
         "--others",
         "--exclude-standard",
         "-z"
-    ]);
+    ])).filter(
+    // Indexed runtime was rejected above; only generated, untracked output is excluded.
+    (path) => !path.startsWith(".agent-ops/tasks/") &&
+        !path.startsWith(".agent-ops/reviews/"));
     return {
         staged,
         unstaged,

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

@@ -47,6 +47,9 @@ export function isPassingVerificationEvidence(command, evidence) {
     if (evidence.status !== "PASS" ||
         evidence.exitCode !== 0 ||
         evidence.failureClass !== "none" ||
+        evidence.cwd !== command.cwd ||
+        JSON.stringify(evidence.argv) !==
+            JSON.stringify([command.command, ...command.args].map(redactSecrets)) ||
         command.evidence.kind === "file") {
         return false;
     }
@@ -96,7 +99,12 @@ export class FileEvidenceStore {
             return null;
         }
         try {
-            return JSON.parse(source);
+            const validation = validateEvidence(JSON.parse(source));
+            if (!validation.ok)
+                return null;
+            const evidence = validation.value;
+            const expected = `.agent-ops/tasks/evidence/${evidence.taskId}/${evidence.commandId}-${sha256(source).slice(0, 16)}.json`;
+            return reference === expected ? evidence : null;
         }
         catch {
             throw new AgentOpsError("EVIDENCE_INVALID", "Stored evidence is not valid JSON.");

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

@@ -123,7 +123,15 @@ export class VerificationService {
             ? await collectChangeSurface(this.#options.gitRunner)
             : { staged: [], unstaged: [], untracked: [], paths: reviewScope.changedFiles };
         const surface = worktreeSurface;
-        const selection = selectVerificationScope(surface.paths, this.#options.config);
+        const mappedSelection = selectVerificationScope(surface.paths, this.#options.config);
+        const taskVerifierIds = new Set(validation.value.criteria.flatMap((criterion) => criterion.verifierIds));
+        const selection = {
+            ...mappedSelection,
+            verifierIds: [...new Set([...mappedSelection.verifierIds,
+                    ...this.#options.config.verification.commands
+                        .filter(({ id, required }) => required && taskVerifierIds.has(id))
+                        .map(({ id }) => id)])]
+        };
         const results = [];
         for (const commandId of selection.verifierIds) {
             results.push(await this.#runCommand(validation.value, commandById(this.#options.config, commandId)));

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/en/spec/acceptance-and-evidence.md

@@ -19,3 +19,28 @@ The verifier MUST return FAIL when a criterion is missing, duplicated, unknown,
 - Evidence: The aggregate lists the criterion IDs and their evidence references.
 - Positive: `tests PASS [report.json]; scope PASS [diff.txt]`.
 - Negative: `tests PASS; tests PASS; extra PASS`.
+
+## EVIDENCE-COMPLETION-001
+
+`agent-ops task complete` MUST validate completion independently of the host, active profiles, and Stop hooks.
+
+- Trigger: Completing a task, including repeated completion requests.
+- Action: Check required verifiers, current evidence, whole-task review, and subtask completion before writing state.
+- Evidence: `TASK_COMPLETED` is returned only after these checks pass; rejected requests preserve state.
+- Positive: Current verification evidence plus a task-bound review allows an otherwise complete task to finish.
+- Negative: Supplying `criterion=PASS`, an old review, or archiving an unfinished child to bypass completion.
+
+- Every criterion needs at least one required verifier and current PASS evidence for every required verifier it names. Verify always includes those task-required commands, even when path mappings select a narrower set. Supply the evidence file references produced by `agent-ops verify --task <id>`, not command strings or a written assertion of PASS.
+- The task's config baseline and evidence must match the current effective config and source fingerprint in the selected scope. Outstanding verification failures block completion. A newer failing result cannot be replaced by an older PASS; contradictory results at the same timestamp fail closed.
+- Run `agent-ops review --task <id> --yes` for the whole task. Completion requires its current, task-bound PASS attestation; generic reviews and partial-criterion reviews do not satisfy it.
+- Starting an authorized review invalidates the previous attestation for that source fingerprint. If the reviewer cannot run or does not pass, run a fresh successful whole-task review before completion.
+- All subtasks and descendants must have completed without an outstanding failure. Archiving unfinished work does not satisfy this requirement. A completed or archived parent cannot accept new subtasks. If a subtask is abandoned, recreate the parent task without that cancelled branch and verify/review the new task tree.
+- Evidence, source and config validation run outside the task store lock. After rechecking source and config, completion briefly locks state, rejects a changed task snapshot (`TASK_COMPLETION_STATE_CHANGED`), rechecks descendants, and writes completion atomically. Slow validation does not block task reads or other task mutations; a concurrent mutation remains intact when completion is rejected.
+
+Existing task files remain readable without migration. Legacy tasks without a config baseline, arbitrary evidence references, or unfinished archived children must be recreated and verified/reviewed before completion. Repeating completion also revalidates the evidence; an old completed status alone is insufficient. Runtime callers must supply `TaskServiceOptions.completion`; omitting this repository context fails closed for completion while leaving read-only task operations available.
+
+Before committing, use the default worktree scope for verify, review and completion. After committing, use the same `--base <git-ref>` on all three commands to produce fresh proof for that committed range; `TaskServiceOptions.completion.base` selects it for runtime callers. Base mode requires a clean worktree. Without a worktree change surface or an explicit base, completion returns `TASK_COMPLETION_SCOPE_REQUIRED`. The agy Stop gate still checks worktree-scoped proof: complete and stop before committing, or use its user-approved one-time permit after inspecting a completed base-scoped task.
+
+This enforces the toolkit's completion command, not a host's natural-language completion claim. It does not prevent a process with the same filesystem authority from editing task/evidence files directly, and it does not lock Git or external source writers.
+
+Project init/update installs `.agent-ops/.gitignore` for `/tasks/` and `/reviews/` on every harness and profile. An existing user-owned `.agent-ops/.gitignore` blocks init/update with `UNMANAGED_INSTALL_PATH`: first back it up outside that path and move its custom rules to the root `.gitignore` (prefix them with `/.agent-ops/`), then retry. Git collection fails with `CHANGE_SURFACE_TRACKED_RUNTIME` if these directories contain indexed files (even clean tracked files), or staged runtime removals. Move any real source files out of the runtime directories, install ignore rules, then use `git rm -r --cached --ignore-unmatch -- .agent-ops/tasks/ .agent-ops/reviews/` to keep local files while removing them from the index. Commit any staged removals before producing fresh verification/review evidence. The active completion Stop gate also blocks this condition with `COMPLETION_GATE_TRACKED_RUNTIME` and the recovery message. Run verify/review from the Git repository root; nested project roots are not supported by the current path/fingerprint collector. Uninstall removes the managed ignore file but preserves runtime output.

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/docs/zh-TW/spec/acceptance-and-evidence.md

@@ -1,6 +1,6 @@
 # 驗收與證據
 
-English source version: 2026-07-23. Revalidate: when the English specification changes.
+English source version: 2026-09-07. Revalidate: when the English specification changes.
 
 ## EVIDENCE-CRITERION-001
 
@@ -21,3 +21,28 @@ English source version: 2026-07-23. Revalidate: when the English specification c
 - Evidence: 聚合結果列出 criterion ID 與證據參照。
 - Positive: `tests PASS [report.json]；scope PASS [diff.txt]`。
 - Negative: `tests PASS；tests PASS；extra PASS`。
+
+## EVIDENCE-COMPLETION-001
+
+`agent-ops task complete` MUST 獨立於 host、啟用的 profile 與 Stop hook，驗證任務是否可完成。
+
+- Trigger: 完成任務，包括重複提交完成請求。
+- Action: 寫入狀態前檢查 required verifier、目前有效的證據、全任務審查與子任務完成狀態。
+- Evidence: 僅在檢查通過後回傳 `TASK_COMPLETED`；拒絕請求時保留原狀態。
+- Positive: 有目前有效的驗證證據與 task-bound review，且子任務已完成，才允許收口。
+- Negative: 填入 `criterion=PASS`、提供舊 review，或封存未完成子任務來繞過檢查。
+
+- 每項 criterion 至少需要一個 required verifier，且其列出的每個 required verifier 都要有目前有效的 PASS evidence。即使 path mapping 選出較小範圍，verify 也會包含 task 明列的 required 命令。請提供 `agent-ops verify --task <id>` 產生的證據檔參照，不能只填命令文字或自行宣稱 PASS。
+- 任務的 config baseline、evidence 必須符合目前有效設定與所選 scope 的來源指紋。尚未解決的驗證失敗會阻擋完成；舊 PASS 不能蓋過較新的失敗，同時間戳的矛盾結果也會阻擋。
+- 使用 `agent-ops review --task <id> --yes` 審查整個任務。完成時必須有目前有效且綁定該 task 的 PASS attestation；generic review 與只涵蓋部分 criterion 的 review 不算。
+- 開始一次已授權的 review 會撤銷該來源指紋先前的 attestation。若 reviewer 未能執行或未通過，完成前必須重新取得成功的全任務 review。
+- 所有子任務與後代任務都必須已完成，且沒有尚未解決的失敗。封存未完成工作不算完成；已完成或封存的 parent 不能新增子任務。若放棄某個 subtask，請重建不含該取消分支的 parent task，並重新驗證與審查新的 task tree。
+- 證據、來源與設定檢查在 task store 鎖外執行。再次確認來源與設定後，完成操作才短暫鎖住狀態，比對 task 快照（改變時回傳 `TASK_COMPLETION_STATE_CHANGED`）、重查後代任務並原子寫入。慢速檢查不會阻擋 task 讀取或其他修改；完成被拒絕時，併發修改仍會保留。
+
+既有 task 檔案仍可直接讀取，不需資料格式遷移。缺少 config baseline、使用任意文字證據，或含有未完成但已封存子任務的舊任務，必須重建並完成驗證與審查。重複執行 complete 也會重新驗證證據；舊的 completed 狀態本身不夠。Runtime 呼叫端必須提供 `TaskServiceOptions.completion`；缺少此 repository context 時，complete 會拒絕執行，但仍可讀取任務。
+
+Commit 前，verify、review、complete 使用預設 worktree scope。Commit 後，三個命令都使用相同的 `--base <git-ref>`，為已提交範圍重新產生證據；runtime 呼叫端使用 `TaskServiceOptions.completion.base`。Base 模式要求 worktree 乾淨。沒有 worktree 變更又未指定 base 時，complete 會回傳 `TASK_COMPLETION_SCOPE_REQUIRED`。agy Stop gate 仍檢查 worktree scope 的證據：請在 commit 前完成並停止，或由使用者檢查已完成的 base-scope 任務後，核准一次性的 Stop permit。
+
+這項機制強制的是 toolkit 的完成命令，無法阻止 host 直接用自然語言宣稱完成，也無法阻止具有相同檔案權限的 process 直接改寫 task／evidence 檔案；它不會鎖住 Git 或其他來源檔案寫入者。
+
+Project init/update 在所有 harness 與 profile 安裝 `.agent-ops/.gitignore`，忽略 `/tasks/` 與 `/reviews/`；若已有使用者自建的 `.agent-ops/.gitignore`，init/update 會回傳 `UNMANAGED_INSTALL_PATH`：先將原檔備份到其他位置，並將自訂規則移到根目錄 `.gitignore`（加上 `/.agent-ops/` 前綴），再重試。這些目錄若包含 index 中的檔案（即使 tracked 且未修改）或 staged 的 runtime 刪除，Git 範圍收集會回傳 `CHANGE_SURFACE_TRACKED_RUNTIME`。請先移出真正的程式來源、安裝 ignore 規則，再執行 `git rm -r --cached --ignore-unmatch -- .agent-ops/tasks/ .agent-ops/reviews/`，保留本機檔案並解除追蹤。若有 staged 刪除，先提交清理 commit，再重新產生 verify/review 證據。啟用的 completion Stop gate 也會以 `COMPLETION_GATE_TRACKED_RUNTIME` 阻擋此狀況並提供修復訊息。請從 Git repository 根目錄執行 verify/review；目前路徑與指紋收集不支援巢狀 project root。Uninstall 會移除 managed ignore 檔，但保留 runtime 輸出。

package/package.json

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