@kylecheng3146/agent-ops 0.3.0 → 0.3.1

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

@@ -3,7 +3,7 @@ import { readFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { execFile, execFileSync, spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { commonHarnessAdapters, harnessHookPath, HARNESS_IDS } from "../../../runtime/src/install/harness.js";
 import { agyRuntimeStatus, agyVersionSupported, hookRegistrationDrift, repositoryTrustStatus, smokeAvailabilityStatus } from "../../../runtime/src/install/probes.js";
@@ -12,8 +12,6 @@ import { readRecordedSessionId } from "../../../runtime/src/hooks/codex-loop.js"
 import { NpmRegistryClient } from "../../../runtime/src/registry/npm.js";
 import { TaskService } from "../../../runtime/src/task/service.js";
 import { FileTaskStore } from "../../../runtime/src/task/store.js";
-import { FileTrustStore } from "../../../runtime/src/security/trust.js";
-import { localStatePaths } from "../../../runtime/src/security/permissions.js";
 import { calculateConfigHash } from "../../../runtime/src/config/hash.js";
 import { FileEvidenceStore } from "../../../runtime/src/verify/evidence.js";
 import { calculateSourceFingerprint } from "../../../runtime/src/verify/source-fingerprint.js";
@@ -22,6 +20,7 @@ import { NodeVerificationProcessRunner } from "../../../runtime/src/verify/spawn
 import { runCli } from "./cli.js";
 import { loadEffectiveConfig, repositoryTrust, repositoryTrustBinding } from "./context.js";
 import { runHookProcess } from "./hook-process.js";
+import { gitRunner, trustStore, worktreeDependencies } from "./parallel-deps.js";
 import { selectYesNo, writeBanner } from "./ui.js";
 import { CLI_VERSION } from "./version.js";
 import { createCommandRegistry } from "./commands/index.js";
@@ -43,6 +42,7 @@ import { formatUpdatePlan, runUpdateCommand } from "./commands/update.js";
 import { errorEnvelope } from "./output.js";
 import { runAgyHeadless } from "./agy-headless.js";
 import { runWorktreeCommand } from "./commands/parallel.js";
+import { ensureSessionWorktree, resolveCheckouts } from "../../../runtime/src/parallel/service.js";
 import { listWorktrees, worktreeDoctorResult } from "../../../runtime/src/parallel/manage.js";
 const HOOK_RUNTIME_PATH = fileURLToPath(new URL("./hook-entry.js", import.meta.url));
 async function readOptionalText(path) {
@@ -78,29 +78,6 @@ async function installedManifest(root) {
 async function installedHarness(root) {
     return (await installedManifest(root))?.harness ?? [...HARNESS_IDS];
 }
-function gitRunner(root) {
-    return {
-        run: async (gitArgs) => {
-            try {
-                return {
-                    exitCode: 0,
-                    stdout: execFileSync("git", [...gitArgs], {
-                        cwd: root,
-                        encoding: "buffer",
-                        stdio: ["ignore", "pipe", "ignore"]
-                    })
-                };
-            }
-            catch (error) {
-                const failure = error;
-                return {
-                    exitCode: failure.status ?? 1,
-                    stdout: failure.stdout ?? new Uint8Array()
-                };
-            }
-        }
-    };
-}
 async function confirmInit(plan, trust, warnings = []) {
     writeBanner({
         isTTY: process.stdout.isTTY === true,
@@ -113,59 +90,12 @@ async function confirmPlan(text) {
     process.stdout.write(text);
     return await selectYesNo("Apply this installation plan?", { input: process.stdin, output: process.stdout }, false);
 }
-function trustStore() {
-    const state = localStatePaths(process.env.AGENT_OPS_HOME ?? homedir());
-    return new FileTrustStore(state.trustStore, state.anchorDirectory);
-}
 async function plannedTrustBinding(root, projectConfig) {
     const config = (await loadEffectiveConfig(root, "project", projectConfig)).config;
     return config.verification.commands.length === 0
         ? null
         : await repositoryTrustBinding(root, config, CLI_VERSION);
 }
-function worktreeDependencies() {
-    const gateFor = async (root, config) => new CompletionGateService({
-        root,
-        config,
-        gitRunner: gitRunner(root),
-        taskService: new TaskService(new FileTaskStore(join(root, ".agent-ops", "tasks", "state.json"), root)),
-        evidenceStore: new FileEvidenceStore(root, root)
-    });
-    return {
-        git: async (cwd, gitArgs) => await new Promise((resolve) => {
-            execFile("git", [...gitArgs], { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }, (error, stdout, stderr) => resolve({
-                exitCode: error === null ? 0 : typeof error.code === "number" ? error.code : 1,
-                stdout,
-                stderr
-            }));
-        }),
-        loadConfig: async (root) => (await loadEffectiveConfig(root, "project")).config,
-        trust: {
-            status: async (root, config) => await repositoryTrust(root, config, CLI_VERSION),
-            grant: async (root, config) => await trustStore().grant(await repositoryTrustBinding(root, config, CLI_VERSION)),
-            revoke: async (root, config) => {
-                await trustStore().revoke(await repositoryTrustBinding(root, config, CLI_VERSION));
-            }
-        },
-        gate: gateFor,
-        tasks: (root) => new TaskService(new FileTaskStore(join(root, ".agent-ops", "tasks", "state.json"), root)),
-        processRunner: new NodeVerificationProcessRunner(),
-        runSetup: async (cwd, step) => await new Promise((resolve) => {
-            execFile(step.command, [...step.args], {
-                cwd,
-                encoding: "utf8",
-                timeout: step.timeoutMs,
-                maxBuffer: 16 * 1024 * 1024,
-                ...(process.platform === "win32" ? { shell: true } : {})
-            }, (error, stdout, stderr) => resolve({
-                exitCode: error === null
-                    ? 0
-                    : typeof error.code === "number" && error.killed !== true ? error.code : null,
-                output: `${stdout}${stderr}`
-            }));
-        })
-    };
-}
 async function worktreeDoctorProbe(root) {
     let statuses;
     try {
@@ -222,7 +152,7 @@ else if (argv[0] === "hook") {
         stdin: process.stdin,
         writeStdout: (value) => process.stdout.write(value),
         writeStderr: (value) => process.stderr.write(value)
-    }, CLI_VERSION);
+    }, CLI_VERSION, { worktree: worktreeDependencies() });
 }
 else {
     process.exitCode = await runCli(argv, {
@@ -448,14 +378,40 @@ else {
                     // run inside a session is never told which session it is in.
                     const sessionId = process.env.AGENT_OPS_SESSION_ID ??
                         await readRecordedSessionId(root);
-                    const policyConfigHash = args.action === "create"
-                        ? calculateConfigHash((await loadEffectiveConfig(root, args.scope === "user" ? "user" : "project")).config)
+                    const createConfig = args.action === "create"
+                        ? (await loadEffectiveConfig(root, args.scope === "user" ? "user" : "project")).config
                         : undefined;
+                    const policyConfigHash = createConfig === undefined
+                        ? undefined
+                        : calculateConfigHash(createConfig);
+                    // Auto mode starts the work where it belongs: a task created from
+                    // the main checkout lands in the session's own worktree.
+                    const worktreeDeps = worktreeDependencies();
+                    const fromMain = createConfig?.worktree?.mode === "auto" &&
+                        args.scope !== "user" &&
+                        await resolveCheckouts(worktreeDeps, root)
+                            .then(({ mainRoot, currentRoot }) => mainRoot === currentRoot)
+                            .catch(() => false);
                     return await runTaskCommand({
                         args,
                         service: taskService,
                         ...(policyConfigHash === undefined ? {} : { policyConfigHash }),
-                        ...(sessionId === undefined ? {} : { sessionId })
+                        ...(sessionId === undefined ? {} : { sessionId }),
+                        ...(fromMain
+                            ? {
+                                sessionWorktree: async (session) => {
+                                    const record = await ensureSessionWorktree(worktreeDeps, {
+                                        cwd: root,
+                                        sessionId: session
+                                    });
+                                    return {
+                                        path: record.path,
+                                        base: record.base,
+                                        service: new TaskService(new FileTaskStore(join(record.path, ".agent-ops", "tasks", "state.json"), record.path))
+                                    };
+                                }
+                            }
+                            : {})
                     });
                 }
                 if (args.command === "review") {

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

@@ -28,16 +28,17 @@ function addText(result) {
         "Work only inside that path from now on:",
         `- Claude Code: EnterWorktree with path ${record.path}`,
         `- Codex and agy: run every command with ${record.path} as its working directory`,
-        `Finish with: commit, agent-ops verify/review/task complete with --base ${record.base},`,
-        `then agent-ops worktree finish ${record.name} from ${record.mainRoot}`,
-        "(Claude Code: ExitWorktree with action keep before finishing)."
+        `Finish with: commit, agent-ops verify and review with --base ${record.base},`,
+        `then agent-ops worktree finish ${record.name} from ${record.mainRoot}, which`,
+        "completes every task in the worktree and merges",
+        "(Claude Code: ExitWorktree with action keep before finishing; do not run task complete in the worktree)."
     ].join("\n");
 }
 function finishText(result) {
     const { record } = result;
     return [
         `Merged ${record.branch} into ${record.targetBranch} at ${result.mergedHead}${result.rebased ? " after a clean rebase and re-verification" : ""}.`,
-        `Task ${result.taskId} is recorded in git notes (refs/notes/agent-ops).`,
+        `Completed and recorded in git notes (refs/notes/agent-ops): ${result.taskIds.join(", ")}.`,
         `Removed ${record.path}.`,
         ...result.warnings.map((warning) => `Warning: ${warning}`)
     ].join("\n");

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

@@ -273,7 +273,7 @@ async function reusableReview(options, sourceFingerprint, context) {
     if (options.root === undefined) {
         return null;
     }
-    const attestation = await findReviewAttestation(options.root, sourceFingerprint);
+    const attestation = await findReviewAttestation(options.root, sourceFingerprint, context?.taskId);
     if (attestation === null || attestation.taskId !== context?.taskId) {
         return null;
     }
@@ -284,7 +284,7 @@ async function reusableReview(options, sourceFingerprint, context) {
         context?.policyConfigHash !== options.policyConfigHash) {
         return null;
     }
-    const artifact = await readReviewReportArtifact(options.root, sourceFingerprint);
+    const artifact = await readReviewReportArtifact(options.root, sourceFingerprint, attestation.taskId);
     if (artifact === null ||
         artifact.taskId !== attestation.taskId ||
         artifact.report === undefined ||
@@ -488,7 +488,7 @@ export async function runReviewCommand(options) {
                     })
                 });
             }
-            await invalidateReviewAttestation(options.root, sourceFingerprint);
+            await invalidateReviewAttestation(options.root, sourceFingerprint, context?.taskId);
             pendingInvalidation = false;
         }
     }
@@ -605,7 +605,9 @@ export async function runReviewCommand(options) {
         await options.tasks.recordEvidence(context.taskId, Object.fromEntries(finalResult.results.map((item) => [
             item.criterionId,
             item.evidence.map((reference) => `review:${finalResult.harness}:${reference}`)
-        ])));
+        ])), 
+        // What `worktree finish` completes this task against.
+        scope?.mode === "base" ? scope.resolvedBase : null);
     }
     const message = finalResult.status === "PASS"
         ? "Independent review passed."

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

@@ -87,7 +87,10 @@ export async function runTaskCommand(options) {
             if (options.args.title === undefined) {
                 throw new AgentOpsError("TASK_TITLE_REQUIRED", "Task creation requires --title.");
             }
-            const record = await options.service.create({
+            const worktree = sessionId === undefined || options.sessionWorktree === undefined
+                ? undefined
+                : await options.sessionWorktree(sessionId);
+            const record = await (worktree?.service ?? options.service).create({
                 title: options.args.title,
                 criteria: (options.args.criteria ?? []).map(parseCriterion),
                 ...(options.policyConfigHash === undefined
@@ -98,9 +101,30 @@ export async function runTaskCommand(options) {
                     : { parentTaskId: options.args.parentTaskId }),
                 ...(sessionId === undefined ? {} : { sessionId })
             });
-            return taskEnvelope(action, "TASK_CREATED", sessionId === undefined
+            const created = taskEnvelope(action, "TASK_CREATED", sessionId === undefined
                 ? `Created task ${record.task.id}.`
-                : `Created and attached task ${record.task.id}.`, record);
+                : record.task.parentTaskId === undefined
+                    ? `Created and attached task ${record.task.id}.`
+                    : `Created subtask ${record.task.id}; the session stays on the top of its task tree.`, record);
+            if (worktree === undefined || created.data === null)
+                return created;
+            return {
+                ...created,
+                data: {
+                    ...created.data,
+                    text: [
+                        `Created in this session's worktree ${worktree.path}.`,
+                        "Work only inside that path from now on:",
+                        `- Claude Code: EnterWorktree with path ${worktree.path}`,
+                        `- Codex and agy: run every command with ${worktree.path} as its working directory`,
+                        `Commit, then run verify and review there with --base ${worktree.base};`,
+                        "then leave the worktree (Claude Code: ExitWorktree with action keep) and run",
+                        "agent-ops worktree finish from the main checkout, which completes the task and merges.",
+                        "",
+                        created.data.text
+                    ].join("\n")
+                }
+            };
         }
         if (action === "status") {
             if (options.args.taskId === undefined && sessionId === undefined) {

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

@@ -3,8 +3,9 @@
 //   node <this file> <harness> <event> --managed-by=agent-ops
 import { CLI_VERSION } from "./version.js";
 import { runHookProcess } from "./hook-process.js";
+import { worktreeDependencies } from "./parallel-deps.js";
 process.exitCode = await runHookProcess(process.argv.slice(2), {
     stdin: process.stdin,
     writeStdout: (value) => process.stdout.write(value),
     writeStderr: (value) => process.stderr.write(value)
-}, CLI_VERSION);
+}, CLI_VERSION, { worktree: worktreeDependencies() });

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

@@ -10,6 +10,7 @@ import { redactSecrets } from "../../../runtime/src/security/redact.js";
 import { claudeStopRecursionMarker } from "../../../runtime/src/adapters/claude/input.js";
 import { HARNESS_IDS, harnessDescriptor } from "../../../runtime/src/install/harness.js";
 import { evaluateWorktreeWrite, resolveMainRoot } from "../../../runtime/src/parallel/guard.js";
+import { ensureSessionWorktree } from "../../../runtime/src/parallel/service.js";
 import { CompletionGateService } from "../../../runtime/src/hooks/completion-gate.js";
 import { TaskService } from "../../../runtime/src/task/service.js";
 import { FileTaskStore } from "../../../runtime/src/task/store.js";
@@ -348,7 +349,9 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
                 const mainRoot = await resolveMainRoot(gitRunner);
                 return mainRoot === null
                     ? { action: "continue", status: "UNKNOWN", code: "WORKTREE_GUARD_UNAVAILABLE" }
-                    : await evaluateWorktreeWrite(mainRoot, write.paths, write.sessionId);
+                    : await evaluateWorktreeWrite(mainRoot, write.paths, write.sessionId, dependencies.worktree === undefined
+                        ? undefined
+                        : async (sessionId) => (await ensureSessionWorktree(dependencies.worktree, { cwd: mainRoot, sessionId })).path);
             }
             : undefined;
         const output = await runHookCommand({

package/dist/packages/cli/src/parallel-deps.js

@@ -0,0 +1,89 @@
+import { execFile, execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CompletionGateService } from "../../../runtime/src/hooks/completion-gate.js";
+import { localStatePaths } from "../../../runtime/src/security/permissions.js";
+import { FileTrustStore } from "../../../runtime/src/security/trust.js";
+import { TaskService } from "../../../runtime/src/task/service.js";
+import { FileTaskStore } from "../../../runtime/src/task/store.js";
+import { FileEvidenceStore } from "../../../runtime/src/verify/evidence.js";
+import { NodeVerificationProcessRunner } from "../../../runtime/src/verify/spawn.js";
+import { loadEffectiveConfig, repositoryTrust, repositoryTrustBinding } from "./context.js";
+import { CLI_VERSION } from "./version.js";
+// Shared by the CLI and the hook entry point: Claude Code runs hooks through
+// hook-entry.js, never bin.js, and its worktree guard needs these too.
+export function gitRunner(root) {
+    return {
+        run: async (gitArgs) => {
+            try {
+                return {
+                    exitCode: 0,
+                    stdout: execFileSync("git", [...gitArgs], {
+                        cwd: root,
+                        encoding: "buffer",
+                        stdio: ["ignore", "pipe", "ignore"]
+                    })
+                };
+            }
+            catch (error) {
+                const failure = error;
+                return {
+                    exitCode: failure.status ?? 1,
+                    stdout: failure.stdout ?? new Uint8Array()
+                };
+            }
+        }
+    };
+}
+export function trustStore() {
+    const state = localStatePaths(process.env.AGENT_OPS_HOME ?? homedir());
+    return new FileTrustStore(state.trustStore, state.anchorDirectory);
+}
+export function worktreeDependencies() {
+    const gateFor = async (root, config) => new CompletionGateService({
+        root,
+        config,
+        gitRunner: gitRunner(root),
+        taskService: new TaskService(new FileTaskStore(join(root, ".agent-ops", "tasks", "state.json"), root)),
+        evidenceStore: new FileEvidenceStore(root, root)
+    });
+    return {
+        git: async (cwd, gitArgs) => await new Promise((resolve) => {
+            execFile("git", [...gitArgs], { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }, (error, stdout, stderr) => resolve({
+                exitCode: error === null ? 0 : typeof error.code === "number" ? error.code : 1,
+                stdout,
+                stderr
+            }));
+        }),
+        loadConfig: async (root) => (await loadEffectiveConfig(root, "project")).config,
+        trust: {
+            status: async (root, config) => await repositoryTrust(root, config, CLI_VERSION),
+            grant: async (root, config) => await trustStore().grant(await repositoryTrustBinding(root, config, CLI_VERSION)),
+            revoke: async (root, config) => {
+                await trustStore().revoke(await repositoryTrustBinding(root, config, CLI_VERSION));
+            }
+        },
+        gate: gateFor,
+        tasks: (root, base) => new TaskService(new FileTaskStore(join(root, ".agent-ops", "tasks", "state.json"), root), base === undefined ? {} : { completion: {
+                root,
+                gitRunner: gitRunner(root),
+                base,
+                loadConfig: async () => (await loadEffectiveConfig(root, "project")).config
+            } }),
+        processRunner: new NodeVerificationProcessRunner(),
+        runSetup: async (cwd, step) => await new Promise((resolve) => {
+            execFile(step.command, [...step.args], {
+                cwd,
+                encoding: "utf8",
+                timeout: step.timeoutMs,
+                maxBuffer: 16 * 1024 * 1024,
+                ...(process.platform === "win32" ? { shell: true } : {})
+            }, (error, stdout, stderr) => resolve({
+                exitCode: error === null
+                    ? 0
+                    : typeof error.code === "number" && error.killed !== true ? error.code : null,
+                output: `${stdout}${stderr}`
+            }));
+        })
+    };
+}

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

@@ -42,7 +42,8 @@ function commandHook(event, runtimePath, completionGate = false) {
             CLAUDE_HOOK_MARKER,
             ...(completionGate ? ["--completion-gate"] : [])
         ],
-        timeout: 30
+        // PreToolUse may create the session's worktree, setup steps included.
+        timeout: event === "PreToolUse" ? 600 : 30
     };
 }
 function matcherGroup(event, runtimePath, completionGate = false) {

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

@@ -228,7 +228,7 @@ export class CompletionGateService {
             this.#options.config.worktree?.mode === "auto" &&
             state.root === undefined &&
             await readWorktreeRecord(this.#options.root) === null) {
-            return gateResult("continue", "UNKNOWN", "COMPLETION_GATE_WORKTREE_MODE", `worktree.mode is auto. Session: ${sessionId}. Before your first edit run agent-ops worktree add <name> --session ${shellQuote(sessionId)} and work only inside the printed path.`);
+            return gateResult("continue", "UNKNOWN", "COMPLETION_GATE_WORKTREE_MODE", `worktree.mode is auto. Session: ${sessionId}. Before your first edit run agent-ops task create from this checkout, which creates this session's worktree and puts the task there (or agent-ops worktree add <name> --session ${shellQuote(sessionId)}), and work only inside the printed path. Verify and review there, then finish with agent-ops worktree finish from this checkout, which completes the tasks; do not run task complete in the worktree.`);
         }
         return gateResult("continue", changed ? "UNKNOWN" : "PASS", changed ? "COMPLETION_GATE_CHANGED" : "COMPLETION_GATE_READY", changed
             ? `Git-visible changes require an attached completed task, current PASS evidence, and a PASS review. Session: ${sessionId}. Create with --session ${sessionId}; one-time permit: agent-ops allow-stop --session ${sessionId}.`

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

@@ -311,7 +311,7 @@ export function managedRules(descriptor, context) {
         lines.push("For every change:", "", "1. Define two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope and preserve unrelated changes.", "3. Apply the smallest safe change.", "4. Run evidence-producing verification for every criterion.", "5. Obtain complete independent review before claiming completion, via", "   `agent-ops review --task <task-id> --yes` (or the CLI's equivalent invocation).", "   Never call a", "   review-target CLI (agy, codex, claude) directly — direct calls skip", "   the enforced read-only sandbox flags and can hang or fail on command", "   permission prompts.", "   Start this command through the trusted outer host runner as its first", "   and only invocation. On Codex, the outer tool request must use", "   `sandbox_permissions: \"require_escalated\"` so network and loopback", "   are available; in that same request, unset", "   `CODEX_SANDBOX_NETWORK_DISABLED` and set `AGENT_OPS_HOST` when three", "   targets are configured. The Codex shell form is", "   `env -u CODEX_SANDBOX_NETWORK_DISABLED AGENT_OPS_HOST=<current-host> agent-ops review --task <task-id> --yes`.", "   Do not run it once in the restricted sandbox and retry; changing the", "   variable inside that sandbox is not elevation.", "   Review runs exactly two fresh sessions: with three configured targets,", "   set `AGENT_OPS_HOST` to the current CLI id so it is excluded; with two", "   targets both run in configured order; with one target it runs twice.", "   The first session is necessary; a PASS then requires an adversarial", "   re-check carrying the first report. A first FAIL or NOT_RUN stops.", "", "Treat `.agent-ops/config.json` as verifier authority. Discovery output is", "only a proposal until a user confirms it. Repository commands require an", "exact matching trust record. Confirmed project init/update grants it", "automatically when verification commands are configured.", "");
     }
     if (context.capabilities.includes("task")) {
-        lines.push("Split a change that exceeds five acceptance criteria into subtasks:", "`agent-ops task create --parent <task-id>` records one, and", "`agent-ops task status --parent <task-id>` lists them. Each subtask", "carries its own criteria, verification, and independent review;", "completing one never completes its parent.", "", "Delegate a subtask whose scope spans unknown files, broad scans, or an", "independent workstream instead of doing it inline. Name the bounded", "scope, the artifact to return, and the acceptance criteria it serves.", subagentInstruction(descriptor), "Read every returned artifact back yourself: integration, verification,", "and review stay with the coordinator.", "", "One writer at a time. `agent-ops verify` and `agent-ops review`", "fingerprint the working tree and report UNKNOWN when anything else", "writes it during the run, so delegate edits to one subagent at a time,", "or give each writer its own Git worktree and merge before verifying.", "Read-only delegation has no such limit and may run in parallel.", "", "Parallel conversations in one repository each need their own worktree.", "When `.agent-ops/config.json` sets `worktree.mode` to `auto`, run", "`agent-ops worktree add <name> --session <session-id>` from the main", "checkout before your first edit, and work only inside the printed path", "(Claude Code: EnterWorktree with that path; otherwise use it as every", "command's working directory). Commit, then run verify, review and", "`task complete` with the printed `--base`; leave the worktree (Claude", "Code: ExitWorktree with action keep) and run `agent-ops worktree finish", "<name>` from the main checkout. A finish that reports a conflict is", "resolved once, as a new task whose criteria cover both intents; if its", "verification or review fails, reset as instructed and report.", "");
+        lines.push("Split a change that exceeds five acceptance criteria into subtasks:", "`agent-ops task create --parent <task-id>` records one, and", "`agent-ops task status --parent <task-id>` lists them. Each subtask", "carries its own criteria, verification, and independent review;", "completing one never completes its parent.", "", "Delegate a subtask whose scope spans unknown files, broad scans, or an", "independent workstream instead of doing it inline. Name the bounded", "scope, the artifact to return, and the acceptance criteria it serves.", subagentInstruction(descriptor), "Read every returned artifact back yourself: integration, verification,", "and review stay with the coordinator.", "", "One writer at a time. `agent-ops verify` and `agent-ops review`", "fingerprint the working tree and report UNKNOWN when anything else", "writes it during the run, so delegate edits to one subagent at a time,", "or give each writer its own Git worktree and merge before verifying.", "Read-only delegation has no such limit and may run in parallel.", "", "Parallel conversations in one repository each need their own worktree.", "When `.agent-ops/config.json` sets `worktree.mode` to `auto`, run", "`agent-ops task create` from the main checkout before your first edit:", "it creates this session's worktree and puts the task there (`agent-ops", "worktree add <name> --session <session-id>` does the same without a", "task). Work only inside the printed path", "(Claude Code: EnterWorktree with that path; otherwise use it as every", "command's working directory). Commit, then run verify and review for", "each task with the printed `--base`; do not run `task complete` in the", "worktree. Leave it (Claude Code: ExitWorktree with action keep) and run", "`agent-ops worktree finish <name>` from the main checkout: it completes", "every task in the worktree, subtasks first, then merges. A finish that", "reports an incomplete task names it; verify or review that task again", "in the worktree and finish again. A finish that reports a conflict is", "resolved once, as a new task whose criteria cover both intents; if its", "verification or review fails, reset as instructed and report.", "");
     }
     if (context.capabilities.includes("lifecycle-summary")) {
         lines.push("Advisory lifecycle summaries and local logs are informational. Advisory", "failures must remain fail-open and cannot become verification evidence.", "");

package/dist/runtime/src/parallel/finish.js

@@ -159,12 +159,35 @@ async function targetIntents(deps, cwd, target) {
     }
     return intents;
 }
-function noteText(record, task) {
+/** Each tree top first, its subtasks after it; `depth` counts parents. */
+function taskTree(tasks) {
+    const ids = new Set(tasks.map(({ task }) => task.id));
+    const ordered = [];
+    const visit = (parent, depth) => {
+        for (const task of tasks) {
+            const own = task.task.parentTaskId !== undefined && ids.has(task.task.parentTaskId)
+                ? task.task.parentTaskId
+                : undefined;
+            if (own === parent) {
+                ordered.push({ task, depth });
+                visit(task.task.id, depth + 1);
+            }
+        }
+    };
+    visit(undefined, 0);
+    return ordered;
+}
+function noteText(record, tasks) {
     return [
-        `agent-ops task ${task.task.id}: ${task.task.title}`,
         `worktree: ${record.name} (${record.branch})`,
-        "criteria:",
-        ...task.task.criteria.map(({ id, description }) => `- ${id}: ${description}`)
+        ...tasks.flatMap(({ task, depth }) => {
+            const indent = "  ".repeat(depth);
+            return [
+                `${indent}agent-ops task ${task.task.id}: ${task.task.title}`,
+                `${indent}criteria:`,
+                ...task.task.criteria.map(({ id, description }) => `${indent}- ${id}: ${description}`)
+            ];
+        })
     ].join("\n");
 }
 /**
@@ -200,12 +223,29 @@ export async function finishWorktree(deps, options) {
             throw finishError("WORKTREE_NOTHING_TO_MERGE", `${record.branch} has no commits beyond ${record.targetBranch}; remove the worktree instead.`);
         }
         const worktreeConfig = await deps.loadConfig(record.path);
+        // The whole branch merges, so every task in the worktree completes first,
+        // subtasks before their parents, each over the range its review covered.
+        // Before any rebase: rebasing rewrites the commits those fingerprints name.
+        const tree = taskTree((await deps.tasks(record.path).list()).filter(({ status }) => status !== "archived"));
+        if (tree.length === 0) {
+            throw finishError("WORKTREE_TASK_INCOMPLETE", "The worktree has no task; create one, verify and review it before finishing.");
+        }
+        for (const { task } of [...tree].sort((left, right) => right.depth - left.depth)) {
+            if (task.status === "complete")
+                continue;
+            const base = task.reviewBase ?? record.base;
+            try {
+                await deps.tasks(record.path, base).complete(task.task.id, {});
+            }
+            catch (error) {
+                throw finishError("WORKTREE_TASK_INCOMPLETE", `Task ${task.task.id} (${task.task.title}) could not be completed against ${base}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
         const worktreeGate = await deps.gate(record.path, worktreeConfig);
         const problem = await worktreeGate.validate(record.sessionId);
         if (problem !== null) {
             throw finishError("WORKTREE_TASK_INCOMPLETE", `The worktree's task is not ready to merge (${problem.code}). ${problem.remedy ?? ""}`.trim());
         }
-        const task = await deps.tasks(record.path).status({ sessionId: record.sessionId });
         const head = await git(deps, record.path, ["rev-parse", "HEAD"], "WORKTREE_LOG_FAILED", "Git could not read HEAD.");
         const fastForward = (await deps.git(record.path, ["merge-base", "--is-ancestor", target, "HEAD"])).exitCode === 0;
         if (!fastForward) {
@@ -248,7 +288,7 @@ export async function finishWorktree(deps, options) {
                 warnings.push(`${label}: ${error instanceof Error ? error.message : String(error)}`);
             }
         };
-        await attempt("note", async () => await git(deps, mainRoot, ["notes", `--ref=${NOTES_REF}`, "add", "-f", "-m", noteText(record, task), mergedHead], "WORKTREE_NOTE_FAILED", "Git could not write the agent-ops note."));
+        await attempt("note", async () => await git(deps, mainRoot, ["notes", `--ref=${NOTES_REF}`, "add", "-f", "-m", noteText(record, tree), mergedHead], "WORKTREE_NOTE_FAILED", "Git could not write the agent-ops note."));
         if (gateEnabled) {
             await attempt("gate", async () => {
                 const mainGate = await deps.gate(mainRoot, mainConfig);
@@ -258,6 +298,6 @@ export async function finishWorktree(deps, options) {
         }
         await attempt("trust", async () => await deps.trust.revoke(record.path, worktreeConfig));
         await attempt("remove", async () => await removeCheckout(deps, record, true));
-        return { record, mergedHead, rebased: !fastForward, taskId: task.task.id, warnings };
+        return { record, mergedHead, rebased: !fastForward, taskIds: tree.map(({ task }) => task.task.id), warnings };
     });
 }

package/dist/runtime/src/parallel/guard.js

@@ -1,5 +1,5 @@
 import { realpath } from "node:fs/promises";
-import { basename, dirname, join, sep } from "node:path";
+import { basename, dirname, join, relative, sep } from "node:path";
 import { insideWorktreeDirectory } from "./service.js";
 /** The main checkout of the repository `runner` runs in, or null. */
 export async function resolveMainRoot(runner) {
@@ -41,17 +41,34 @@ export async function canonicalPath(path) {
  * `.worktrees/<name>`. Paths outside the repository are not this guard's
  * business.
  */
-export async function evaluateWorktreeWrite(mainRoot, paths, sessionId) {
+export async function evaluateWorktreeWrite(mainRoot, paths, sessionId, 
+/** Creates or reuses this session's worktree and returns its path. */
+ensureWorktree) {
     for (const path of paths) {
         const target = await canonicalPath(path);
         const inMain = target === mainRoot || target.startsWith(`${mainRoot}${sep}`);
         if (inMain && !insideWorktreeDirectory(mainRoot, target)) {
+            let failure = "";
+            if (sessionId !== undefined && ensureWorktree !== undefined) {
+                try {
+                    const worktree = await ensureWorktree(sessionId);
+                    return {
+                        action: "block",
+                        status: "FAIL",
+                        code: "WORKTREE_CREATED",
+                        remedy: `worktree.mode is auto, so this session now has its own worktree at ${worktree}. Enter it (Claude Code: EnterWorktree with path ${worktree}) and redo this edit there, at ${join(worktree, relative(mainRoot, target))}.`
+                    };
+                }
+                catch (error) {
+                    failure = ` Creating this session's worktree failed: ${error instanceof Error ? error.message : String(error)}`;
+                }
+            }
             const session = sessionId ?? "<session-id>";
             return {
                 action: "block",
                 status: "FAIL",
                 code: "WORKTREE_REQUIRED",
-                remedy: `worktree.mode is auto, so the main checkout is shared and not edited directly. Run \`agent-ops worktree add <name> --session ${session}\` in ${mainRoot}, enter the printed path (Claude Code: EnterWorktree with that path), and edit there.`
+                remedy: `worktree.mode is auto, so the main checkout is shared and not edited directly.${failure} Run \`agent-ops worktree add <name> --session ${session}\` in ${mainRoot}, enter the printed path (Claude Code: EnterWorktree with that path), and edit there.`
             };
         }
     }

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

@@ -261,3 +261,21 @@ export async function addWorktree(deps, options) {
         throw error;
     }
 }
+/** `session-` plus the session id's first eight name-safe characters. */
+export function sessionWorktreeName(sessionId) {
+    const slug = sessionId.toLowerCase().replace(/[^a-z0-9]/gu, "").slice(0, 8);
+    return `session-${slug === "" ? "0" : slug}`;
+}
+/**
+ * The worktree `sessionId` works in, created on first use. One already bound
+ * to the same session is reused, so a session blocked twice before it moves
+ * still gets exactly one worktree.
+ */
+export async function ensureSessionWorktree(deps, options) {
+    const { mainRoot } = await resolveCheckouts(deps, options.cwd);
+    const name = sessionWorktreeName(options.sessionId);
+    const existing = await readWorktreeRecord(worktreePath(mainRoot, name));
+    if (existing?.sessionId === options.sessionId)
+        return existing;
+    return (await addWorktree(deps, { cwd: mainRoot, name, sessionId: options.sessionId })).record;
+}

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

@@ -39,8 +39,18 @@ function safePreflight(attempt) {
         ...(attempt.diagnostic === undefined ? {} : { diagnostic: safeText(attempt.diagnostic) })
     };
 }
-function artifactPath(root, fingerprint) {
-    return join(root, ...REVIEW_ATTESTATION_DIRECTORY.split("/"), `${fingerprint}${REVIEW_REPORT_ARTIFACT_SUFFIX}`);
+/**
+ * A task's review records live under `<fingerprint>.<task id>`, so a parent
+ * and its subtask reviewed on the same source each keep their own PASS until
+ * `worktree finish` completes both. A bare `<fingerprint>` is a record with no
+ * task, or one written before records were kept per task; readers fall back
+ * to it.
+ */
+function recordKey(fingerprint, taskId) {
+    return taskId === undefined ? fingerprint : `${fingerprint}.${taskId}`;
+}
+function artifactPath(root, fingerprint, taskId) {
+    return join(root, ...REVIEW_ATTESTATION_DIRECTORY.split("/"), `${recordKey(fingerprint, taskId)}${REVIEW_REPORT_ARTIFACT_SUFFIX}`);
 }
 export function reviewReportDigest(report) {
     return sha256(JSON.stringify(redactReviewReport(report)));
@@ -127,7 +137,8 @@ function matchingReportArtifact(value, attestation) {
         attempts.every((attempt, index) => attempt.sessionId === attestation.reviewSessionIds[index]));
 }
 async function hasMatchingReportArtifact(root, attestation) {
-    const source = await readPrivateFile(artifactPath(root, attestation.sourceFingerprint), root);
+    // `reportArtifact` was validated to name this fingerprint's own record.
+    const source = await readPrivateFile(join(root, ...attestation.reportArtifact.split("/")), root);
     if (source === null) {
         return false;
     }
@@ -150,12 +161,12 @@ export async function saveReviewReportArtifact(root, result, sourceFingerprint,
     if (Buffer.byteLength(serialized, "utf8") > REPORT_ARTIFACT_MAX_BYTES) {
         throw new AgentOpsError("REVIEW_REPORT_ARTIFACT_TOO_LARGE", "Review report artifact exceeds the capture limit.");
     }
-    const relativePath = `${REVIEW_ATTESTATION_DIRECTORY}/${sourceFingerprint}${REVIEW_REPORT_ARTIFACT_SUFFIX}`;
-    await writePrivateFile(artifactPath(root, sourceFingerprint), serialized, root);
+    const relativePath = `${REVIEW_ATTESTATION_DIRECTORY}/${recordKey(sourceFingerprint, taskId)}${REVIEW_REPORT_ARTIFACT_SUFFIX}`;
+    await writePrivateFile(artifactPath(root, sourceFingerprint, taskId), serialized, root);
     return relativePath;
 }
-function attestationPath(root, fingerprint) {
-    return join(root, ...REVIEW_ATTESTATION_DIRECTORY.split("/"), `${fingerprint}.json`);
+function attestationPath(root, fingerprint, taskId) {
+    return join(root, ...REVIEW_ATTESTATION_DIRECTORY.split("/"), `${recordKey(fingerprint, taskId)}.json`);
 }
 function parseAttestation(value) {
     if (typeof value !== "object" || value === null) {
@@ -183,8 +194,12 @@ function parseAttestation(value) {
         typeof record.adversarialReportDigest !== "string" ||
         !DIGEST_PATTERN.test(record.adversarialReportDigest) ||
         typeof record.reportArtifact !== "string" ||
-        record.reportArtifact !==
-            `${REVIEW_ATTESTATION_DIRECTORY}/${record.sourceFingerprint}${REVIEW_REPORT_ARTIFACT_SUFFIX}` ||
+        // Its own per-task record, or the bare one an older review wrote.
+        ![
+            recordKey(record.sourceFingerprint, record.taskId),
+            record.sourceFingerprint
+        ].some((key) => record.reportArtifact ===
+            `${REVIEW_ATTESTATION_DIRECTORY}/${key}${REVIEW_REPORT_ARTIFACT_SUFFIX}`) ||
         (record.hostTarget !== undefined && !isReviewTarget(record.hostTarget)) ||
         typeof record.createdAt !== "string" ||
         !Number.isFinite(Date.parse(record.createdAt))) {
@@ -214,33 +229,61 @@ export async function saveReviewAttestation(root, attestation) {
     if (!(await hasMatchingReportArtifact(root, validated))) {
         throw new AgentOpsError("REVIEW_ATTESTATION_INVALID", "Review attestation has no matching report artifact.");
     }
-    const relativePath = `${REVIEW_ATTESTATION_DIRECTORY}/${validated.sourceFingerprint}.json`;
-    await writePrivateFile(attestationPath(root, validated.sourceFingerprint), `${JSON.stringify(validated, null, 2)}\n`, root);
+    const relativePath = `${REVIEW_ATTESTATION_DIRECTORY}/${recordKey(validated.sourceFingerprint, validated.taskId)}.json`;
+    await writePrivateFile(attestationPath(root, validated.sourceFingerprint, validated.taskId), `${JSON.stringify(validated, null, 2)}\n`, root);
     return relativePath;
 }
 /**
- * Returns the attestation recorded for this exact source state, or null. A
- * malformed file reads as absent: a gate must fail closed on garbage, never
- * treat it as a passing review.
+ * The record keys that may hold `taskId`'s review of this source: its own,
+ * then the bare one. Without a task, every task's record for the source.
  */
-export async function findReviewAttestation(root, sourceFingerprint) {
-    if (!FINGERPRINT_PATTERN.test(sourceFingerprint)) {
-        return null;
-    }
-    const source = await readPrivateFile(attestationPath(root, sourceFingerprint), root);
-    if (source === null) {
-        return null;
+async function candidateKeys(root, sourceFingerprint, taskId, suffix) {
+    if (taskId !== undefined) {
+        return [recordKey(sourceFingerprint, taskId), sourceFingerprint];
     }
+    let names = [];
     try {
-        const attestation = parseAttestation(JSON.parse(source));
-        return attestation?.sourceFingerprint === sourceFingerprint &&
-            await hasMatchingReportArtifact(root, attestation)
-            ? attestation
-            : null;
+        names = await readdir(join(root, ...REVIEW_ATTESTATION_DIRECTORY.split("/")));
     }
     catch {
+        // No reviews yet.
+    }
+    const own = names
+        .filter((name) => name.startsWith(`${sourceFingerprint}.`) && name.endsWith(suffix))
+        .map((name) => name.slice(0, -suffix.length))
+        .filter((key) => key !== sourceFingerprint && !key.endsWith(".reports") &&
+        TASK_ID_PATTERN.test(key.slice(sourceFingerprint.length + 1)));
+    return [sourceFingerprint, ...own];
+}
+/**
+ * Returns the attestation recorded for this exact source state, or null. A
+ * malformed file reads as absent: a gate must fail closed on garbage, never
+ * treat it as a passing review. With `taskId`, only that task's record or the
+ * bare one; callers still check the task the attestation names.
+ */
+export async function findReviewAttestation(root, sourceFingerprint, taskId) {
+    if (!FINGERPRINT_PATTERN.test(sourceFingerprint) ||
+        (taskId !== undefined && !TASK_ID_PATTERN.test(taskId))) {
         return null;
     }
+    for (const key of await candidateKeys(root, sourceFingerprint, taskId, ".json")) {
+        const source = await readPrivateFile(join(root, ...REVIEW_ATTESTATION_DIRECTORY.split("/"), `${key}.json`), root);
+        if (source === null) {
+            continue;
+        }
+        try {
+            const attestation = parseAttestation(JSON.parse(source));
+            if (attestation?.sourceFingerprint === sourceFingerprint &&
+                recordKey(sourceFingerprint, key === sourceFingerprint ? undefined : attestation.taskId) === key &&
+                await hasMatchingReportArtifact(root, attestation)) {
+                return attestation;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
 }
 /**
  * The stored report behind an attestation, for a caller that wants to reuse
@@ -248,35 +291,64 @@ export async function findReviewAttestation(root, sourceFingerprint) {
  * parses, matches this exact source and records a PASS: a reuse path must fail
  * closed exactly like the gates that read the attestation.
  */
-export async function readReviewReportArtifact(root, sourceFingerprint) {
-    if (!FINGERPRINT_PATTERN.test(sourceFingerprint)) {
+export async function readReviewReportArtifact(root, sourceFingerprint, taskId) {
+    if (!FINGERPRINT_PATTERN.test(sourceFingerprint) ||
+        (taskId !== undefined && !TASK_ID_PATTERN.test(taskId))) {
         return null;
     }
-    const source = await readPrivateFile(artifactPath(root, sourceFingerprint), root);
+    const keys = taskId === undefined
+        ? [sourceFingerprint]
+        : [recordKey(sourceFingerprint, taskId), sourceFingerprint];
+    for (const key of keys) {
+        const source = await readPrivateFile(join(root, ...REVIEW_ATTESTATION_DIRECTORY.split("/"), `${key}${REVIEW_REPORT_ARTIFACT_SUFFIX}`), root);
+        if (source === null) {
+            continue;
+        }
+        try {
+            const value = JSON.parse(source);
+            if (value.sourceFingerprint === sourceFingerprint &&
+                value.status === "PASS" &&
+                value.report !== undefined &&
+                value.adversarial !== undefined) {
+                return value;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * A new authorized attempt supersedes any earlier PASS for this source: the
+ * task's own record, and the bare one when it is this task's (or no task's).
+ * Another task's bare record from before per-task records is left alone.
+ */
+export async function invalidateReviewAttestation(root, sourceFingerprint, taskId) {
+    if (!FINGERPRINT_PATTERN.test(sourceFingerprint) ||
+        (taskId !== undefined && !TASK_ID_PATTERN.test(taskId))) {
+        throw new AgentOpsError("REVIEW_ATTESTATION_INVALID", "Invalid source fingerprint.");
+    }
+    if (taskId !== undefined) {
+        const own = attestationPath(root, sourceFingerprint, taskId);
+        if (await readPrivateFile(own, root) !== null) {
+            await writePrivateFile(own, "null\n", root);
+        }
+    }
+    const bare = attestationPath(root, sourceFingerprint);
+    const source = await readPrivateFile(bare, root);
     if (source === null) {
-        return null;
+        return;
     }
+    let owner;
     try {
-        const value = JSON.parse(source);
-        return value.sourceFingerprint === sourceFingerprint &&
-            value.status === "PASS" &&
-            value.report !== undefined &&
-            value.adversarial !== undefined
-            ? value
-            : null;
+        owner = JSON.parse(source)?.taskId;
     }
     catch {
-        return null;
-    }
-}
-/** A new authorized attempt supersedes any earlier PASS for this source. */
-export async function invalidateReviewAttestation(root, sourceFingerprint) {
-    if (!FINGERPRINT_PATTERN.test(sourceFingerprint)) {
-        throw new AgentOpsError("REVIEW_ATTESTATION_INVALID", "Invalid source fingerprint.");
+        owner = undefined;
     }
-    const path = attestationPath(root, sourceFingerprint);
-    if (await readPrivateFile(path, root) !== null) {
-        await writePrivateFile(path, "null\n", root);
+    if (taskId === undefined || owner === undefined || owner === taskId) {
+        await writePrivateFile(bare, "null\n", root);
     }
 }
 /** Prior findings stay a short checklist, never a second report to digest. */
@@ -328,12 +400,15 @@ export async function findPriorFailingFindings(root, taskId) {
     // ponytail: linear scan of every report; index by task if the directory grows large.
     let latest;
     for (const name of names) {
-        const fingerprint = name.slice(0, -REVIEW_REPORT_ARTIFACT_SUFFIX.length);
-        if (!name.endsWith(REVIEW_REPORT_ARTIFACT_SUFFIX) || !FINGERPRINT_PATTERN.test(fingerprint)) {
+        // `<fingerprint>` or `<fingerprint>.<task id>`, then the suffix.
+        const key = name.slice(0, -REVIEW_REPORT_ARTIFACT_SUFFIX.length);
+        const fingerprint = key.slice(0, 64);
+        if (!name.endsWith(REVIEW_REPORT_ARTIFACT_SUFFIX) || !FINGERPRINT_PATTERN.test(fingerprint) ||
+            (key !== fingerprint && key !== recordKey(fingerprint, taskId))) {
             continue;
         }
         try {
-            const source = await readPrivateFile(artifactPath(root, fingerprint), root);
+            const source = await readPrivateFile(join(directory, name), root);
             if (source === null) {
                 continue;
             }

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

@@ -28,6 +28,17 @@ export const DEFAULT_REVIEW_TIMEOUT_MS = 900_000;
  * thinking hard is never cut off.
  */
 export const DEFAULT_STALL_IDLE_MS = 90_000;
+/**
+ * agy writes nothing to stdout, stderr or its log while one generation
+ * streams, so a long think is indistinguishable from a wedge. Its own logs
+ * show normal generations silent for up to ~177s; 90s cut real reviews off.
+ */
+export const AGY_STALL_IDLE_MS = 240_000;
+/**
+ * A call the service dropped before answering. It produced no verdict, so
+ * one fresh retry is not review shopping.
+ */
+const TRANSIENT_NETWORK = /\b(?:network issue|503|service is currently unavailable|ECONNRESET|ETIMEDOUT|socket hang up)\b/iu;
 /** Two rounds at the per-target default: the previous worst case, now bounded. */
 export const DEFAULT_REVIEW_CHAIN_TIMEOUT_MS = 2 * DEFAULT_REVIEW_TIMEOUT_MS;
 /**
@@ -425,7 +436,8 @@ 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 stallIdleMs = options.stallIdleMs ?? DEFAULT_STALL_IDLE_MS;
+        const stallIdleMs = options.stallIdleMs ??
+            (target === "agy" ? AGY_STALL_IDLE_MS : DEFAULT_STALL_IDLE_MS);
         const stallWatch = watchForStall(heartbeatLog, options.signal, stallIdleMs);
         let spawned;
         try {
@@ -481,8 +493,11 @@ async function attemptTarget(request, options) {
         }
         if (spawned.failureClass === "nonzero-exit") {
             const output = `${spawned.stderr}\n${spawned.stdout}`;
-            return skip(rejectedCallReason(output), firstComplaint(spawned.stderr, spawned.stdout) ??
-                `the call was rejected with exit ${spawned.exitCode ?? "unknown"} and no output`);
+            return {
+                ...skip(rejectedCallReason(output), firstComplaint(spawned.stderr, spawned.stdout) ??
+                    `the call was rejected with exit ${spawned.exitCode ?? "unknown"} and no output`),
+                ...(TRANSIENT_NETWORK.test(output) ? { transient: true } : {})
+            };
         }
         if (spawned.failureClass === "signal-exit") {
             return skip("capability-unavailable", `the reviewer exited after ${spawned.signal ?? "an unknown signal"}`);
@@ -522,6 +537,18 @@ async function attemptTarget(request, options) {
         await rm(attemptDirectory, { recursive: true, force: true });
     }
 }
+/**
+ * `attemptTarget`, retried once in a fresh session when the service dropped
+ * the call. Only once: a service that is down stays down.
+ */
+async function attemptTargetWithRetry(request, options) {
+    const first = await attemptTarget(request, options);
+    if (first.kind !== "skip" || first.transient !== true || budgetSpent(options)) {
+        return first;
+    }
+    options.onProgress?.(`${request.target}: ${first.diagnostic} → retrying once`);
+    return attemptTarget(request, options);
+}
 /** Builds the `execute` callback with one necessary and one adversarial review. */
 export function createReviewExecutor(options) {
     const report = options.onProgress ?? (() => { });
@@ -630,7 +657,7 @@ export function createReviewExecutor(options) {
             report("chain: review deadline reached before the first round");
             return { status: "NOT_RUN", reason: "timeout", attempts: [] };
         }
-        const primaryOutcome = await attemptTarget({
+        const primaryOutcome = await attemptTargetWithRetry({
             ...shared,
             target: primaryTarget,
             label: `${primaryTarget}-primary`,
@@ -739,7 +766,7 @@ export function createReviewExecutor(options) {
             };
         }
         // The second round draws on what is left, never a fresh full budget.
-        const adversarialOutcome = await attemptTarget({
+        const adversarialOutcome = await attemptTargetWithRetry({
             ...shared,
             target: adversarialTarget,
             label: `${adversarialTarget}-adversarial`,

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

@@ -38,7 +38,7 @@ export async function checkTaskCompletionEvidence(stored, options) {
             }
         }
     }
-    const attestation = await findReviewAttestation(root, sourceFingerprint);
+    const attestation = await findReviewAttestation(root, sourceFingerprint, stored.task.id);
     if (attestation === null || attestation.taskId !== stored.task.id) {
         return { status: "FAIL", code: "REVIEW_REQUIRED", remedy: `Run agent-ops review --task ${stored.task.id} --yes for the whole task and current source.` };
     }

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

@@ -130,9 +130,17 @@ export class TaskService {
             state.tasks.push(record);
             if (input.sessionId !== undefined) {
                 const currentIndex = state.sessions.findIndex(({ sessionId }) => sessionId === input.sessionId);
+                // A subtask keeps the session on the top of its tree: the completion
+                // gate checks the attached task and everything under it, so attaching
+                // the subtask would let a Stop through with its parent unfinished.
+                let rootId = record.task.id;
+                for (let parentId = record.task.parentTaskId; parentId !== undefined;) {
+                    rootId = parentId;
+                    parentId = state.tasks.find(({ task }) => task.id === parentId)?.task.parentTaskId;
+                }
                 const attachment = {
                     sessionId: input.sessionId,
-                    taskId: record.task.id,
+                    taskId: rootId,
                     attachedAt: now
                 };
                 if (currentIndex === -1) {
@@ -304,7 +312,12 @@ export class TaskService {
      * task accepts evidence: a completed record must stay exactly as it was
      * verified.
      */
-    async recordEvidence(taskId, evidenceInput) {
+    async recordEvidence(taskId, evidenceInput, 
+    /**
+     * A PASS review's base: set records it, null clears it (the review covered
+     * uncommitted work), undefined leaves the record's value alone.
+     */
+    reviewBase) {
         const now = assertTimestamp(this.#now());
         return await this.#store.mutate((state) => {
             const current = findTask(state, taskId);
@@ -328,10 +341,13 @@ export class TaskService {
                     ...new Set([...(evidence[criterionId] ?? []), ...references])
                 ];
             }
+            const { reviewBase: previousBase, ...rest } = current;
+            const base = reviewBase === undefined ? previousBase : reviewBase ?? undefined;
             const updated = {
-                ...current,
+                ...rest,
                 evidence,
-                updatedAt: now
+                updatedAt: now,
+                ...(base === undefined ? {} : { reviewBase: base })
             };
             replaceTask(state, updated);
             return cloneRecord(updated);

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

@@ -66,7 +66,7 @@ function parseTaskRecord(value) {
     ];
     // Every record written before an optional field existed must still parse, so
     // the accepted shapes are every combination of them.
-    const optionalKeys = ["completionBase", "failureFingerprint", "policyConfigHash"];
+    const optionalKeys = ["completionBase", "failureFingerprint", "policyConfigHash", "reviewBase"];
     const allowedKeys = new Set(Array.from({ length: 1 << optionalKeys.length }, (_unused, mask) => [
         ...baseKeys,
         ...optionalKeys.filter((_key, position) => (mask & (1 << position)) !== 0)
@@ -146,6 +146,10 @@ function parseTaskRecord(value) {
         (typeof completionBase !== "string" || !/^[a-f0-9]{40,64}$/u.test(completionBase))) {
         return invalidState("Task state contains an invalid completion base.");
     }
+    if (value.reviewBase !== undefined &&
+        (typeof value.reviewBase !== "string" || !/^[a-f0-9]{40,64}$/u.test(value.reviewBase))) {
+        return invalidState("Task state contains an invalid review base.");
+    }
     return {
         task: task.value,
         status,
@@ -156,7 +160,8 @@ function parseTaskRecord(value) {
         archivedAt: value.archivedAt,
         failureFingerprint,
         policyConfigHash,
-        completionBase
+        completionBase,
+        ...(value.reviewBase === undefined ? {} : { reviewBase: value.reviewBase })
     };
 }
 function parseSession(value) {

package/docs/en/guides/configuration.md

@@ -152,6 +152,17 @@ evidence. Give each editing conversation its own worktree instead:
   On Claude Code a direct Edit or Write of the main checkout outside
   `.worktrees/` is denied (run `agent-ops update` once so the PreToolUse hook
   matches the file tools). Absent or `"off"` keeps today's single checkout.
+- `agent-ops task create` run from the main checkout with a known session
+  creates that session's worktree first (or reuses it) and records the task
+  there, so the work starts in the worktree. Its output names the path to
+  enter and the `--base` to verify against.
+- As a fallback on Claude Code, the first denied edit creates that worktree:
+  `.worktrees/session-<first eight characters of the session id>`, setup
+  included, bound to the session. The denial names the path to enter with
+  EnterWorktree; a later denial for the same session reuses it. If creation
+  fails, the denial says why and falls back to the manual `worktree add`.
+  Run `agent-ops update` once so the PreToolUse hook gets the 600-second
+  timeout setup needs.
 - `add` creates `.worktrees/<name>` on branch `agent-ops/<name>` from the main
   checkout's HEAD and excludes `/.worktrees/` through `.git/info/exclude`,
   never `.gitignore`. It copies the ignored files agent-ops installed and any
@@ -166,10 +177,20 @@ evidence. Give each editing conversation its own worktree instead:
 - The session's completion gate follows it: Claude Code enters the worktree
   with EnterWorktree, and a host that cannot move a session (agy) is judged by
   the worktree's gate through a redirect the main checkout records.
+- In a worktree, verify and review each task but do not run `task complete`
+  (Claude Code refuses it inside an isolated worktree session). `agent-ops
+  worktree finish <name>` completes every non-archived task in the worktree,
+  subtasks before their parents, each against the base its PASS review
+  recorded (the worktree's base when none was recorded), before any rebase.
+  If one cannot complete, nothing merges and the error names the task.
+  Creating a subtask keeps the session attached to the top of its tree, and
+  each task keeps its own review record, so a parent and a subtask reviewed
+  on the same source do not overwrite each other.
 - `agent-ops worktree finish <name>` merges by fast-forward only, one finish
   at a time. If the target moved, it rebases; a clean rebase whose own patch
   is unchanged is re-verified before merging, and a conflict is reported with
-  the `refs/notes/agent-ops` intent of the work that landed first.
+  the `refs/notes/agent-ops` intent of the work that landed first. The note
+  records every task of the worktree, subtasks indented under their parent.
 - `worktree list`, `resume <name> --session <id>` and `remove <name>` manage
   what is left; `remove --force` discards work and asks the user first.
   `doctor` reports worktrees idle for more than seven days.

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

@@ -136,6 +136,14 @@ fingerprint，因此兩個對話修改同一個 checkout 會互相作廢對方
   Write 修改主 checkout 中 `.worktrees/` 以外的檔案會被拒絕（需先執行一次
   `agent-ops update`，讓 PreToolUse hook 比對檔案工具）。未設定或 `"off"` 則維持
   目前的單一 checkout。
+- 在主 checkout、已知 session 的情況下執行 `agent-ops task create`，會先建立（或重用）
+  該 session 的 worktree，並把 task 記錄在那裡，讓工作一開始就在 worktree 內。輸出會列出
+  要進入的路徑與 verify 用的 `--base`。
+- 作為 Claude Code 上的後備，第一次被拒絕的編輯會自動建立該 worktree：
+  `.worktrees/session-<session id 前八個字元>`，包含 setup，並綁定該 session。
+  拒絕訊息會列出要以 EnterWorktree 進入的路徑；同一 session 之後被拒絕時會重用它。
+  建立失敗時，拒絕訊息會說明原因並退回手動 `worktree add`。需先執行一次
+  `agent-ops update`，讓 PreToolUse hook 取得 setup 所需的 600 秒逾時。
 - `add` 從主 checkout 的 HEAD 建立 `.worktrees/<name>` 與 branch
   `agent-ops/<name>`，並透過 `.git/info/exclude`（而非 `.gitignore`）排除
   `/.worktrees/`。它會複製 agent-ops 安裝的 ignored 檔案，以及根目錄
@@ -148,10 +156,17 @@ fingerprint，因此兩個對話修改同一個 checkout 會互相作廢對方
 - Session 的 completion gate 會跟著它：Claude Code 以 EnterWorktree 進入
   worktree；無法移動 session 的 host（agy）則透過主 checkout 記錄的 redirect，
   由 worktree 的 gate 判定。
+- 在 worktree 裡對每個 task 執行 verify 與 review，但不要執行 `task complete`
+  （Claude Code 在隔離的 worktree session 中會拒絕它）。`agent-ops worktree finish
+  <name>` 會在任何 rebase 之前 complete worktree 內每個未封存的 task，先 subtask
+  後 parent，各自使用其 PASS review 記錄的 base（沒有記錄時使用 worktree 的 base）。
+  任一 task 無法完成時不會合併，錯誤訊息會指出是哪個 task。建立 subtask 時 session
+  維持附著在 task 樹最上層，且每個 task 各自保留 review 紀錄，所以在同一份原始碼上
+  review 的 parent 與 subtask 不會互相覆蓋。
 - `agent-ops worktree finish <name>` 只以 fast-forward 合併，一次只執行一個
   finish。Target 若已前進會先 rebase；沒有衝突且自身 patch 不變的 rebase 會先
   重新驗證再合併；衝突則連同先合併那份工作在 `refs/notes/agent-ops` 的意圖一起
-  回報。
+  回報。Note 會記錄 worktree 的每個 task，subtask 縮排在其 parent 之下。
 - `worktree list`、`resume <name> --session <id>` 與 `remove <name>` 管理剩下的
   worktree；`remove --force` 會丟棄工作，執行前會先詢問使用者。`doctor` 會回報
   閒置超過七天的 worktree。

package/package.json

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