@kylecheng3146/agent-ops 0.5.0 → 0.5.1

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

@@ -34,6 +34,7 @@ import { runTaskCommand } from "./commands/task.js";
 import { hasFreshVerification, runReviewCommand } from "./commands/review.js";
 import { runBatchCommand } from "./commands/batch.js";
 import { createSourceGuard } from "../../../runtime/src/review/batch-guard.js";
+import { withReviewSlot } from "../../../runtime/src/review/slots.js";
 import { memoizePreflight } from "../../../runtime/src/review/batch.js";
 import { createReviewExecutor, ReviewInterruptedError } from "../../../runtime/src/review/execute.js";
 import { probeReviewTargetDetailed } from "../../../runtime/src/review/probe.js";
@@ -452,6 +453,25 @@ else {
                     const reviewConfig = (await loadEffectiveConfig(root, reviewArgs.scope === "user" ? "user" : "project")).config;
                     const reviewRole = resolveReviewRole("independent-review", reviewConfig.reviewRoles ?? []);
                     const configuredReviewTargets = reviewRole?.targets ?? [];
+                    // Every worktree of the repository shares this directory, so the
+                    // slots bound reviews across writers, not just within one process.
+                    const commonDirResult = await reviewGit.run([
+                        "rev-parse",
+                        "--path-format=absolute",
+                        "--git-common-dir"
+                    ]);
+                    const slotDir = commonDirResult.exitCode === 0
+                        ? new TextDecoder().decode(commonDirResult.stdout).trim()
+                        : undefined;
+                    const inSlot = (executor) => slotDir === undefined
+                        ? executor
+                        : async (request) => await withReviewSlot({
+                            dir: slotDir,
+                            signal,
+                            onWait: (line) => {
+                                process.stderr.write(`${progressPrefix}${line}\n`);
+                            }
+                        }, async () => await executor(request));
                     return {
                         args: reviewArgs,
                         authorized: reviewArgs.yes,
@@ -470,7 +490,7 @@ else {
                         currentPolicyConfigHash: async () => calculateConfigHash((await loadEffectiveConfig(root, reviewArgs.scope === "user" ? "user" : "project")).config),
                         config: reviewConfig,
                         evidenceStore: new FileEvidenceStore(root, root),
-                        execute: createReviewExecutor({
+                        execute: inSlot(createReviewExecutor({
                             targets: configuredReviewTargets,
                             cwd: root,
                             ...(reviewRole?.model === undefined
@@ -495,7 +515,7 @@ else {
                             onProgress: (line) => {
                                 process.stderr.write(`${progressPrefix}${line}\n`);
                             }
-                        })
+                        }))
                     };
                 };
                 if (args.command === "review") {

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

@@ -11,6 +11,7 @@ function listText(statuses, now) {
         `${record.name}${idle.has(record.name) ? " (idle)" : ""}`,
         `  path: ${record.path}`,
         `  session: ${record.sessionId}`,
+        ...(record.agentId === undefined ? [] : [`  agent: ${record.agentId}`]),
         `  branch: ${record.branch}, ${ahead} commit(s) ahead of ${record.targetBranch}${dirty ? ", uncommitted changes" : ""}`,
         `  task: ${taskStatus}`,
         `  last activity: ${lastActivity}`

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

@@ -6,6 +6,9 @@ import { okEnvelope } from "../output.js";
 import { formatOperationPlan } from "../plan-output.js";
 import { toPublicUpdatePlan } from "../public-plan.js";
 import { formatTrustChange, planTrustGrant } from "./trust.js";
+function repairedLines(plan) {
+    return plan.installation.repaired.map(({ path, reason }) => `repaired: ${path} (${reason.replace("-", " ")})`);
+}
 export function formatUpdatePlan(plan, trust) {
     const detectedVerification = plan.installation.detectedVerification;
     return formatOperationPlan({
@@ -21,6 +24,7 @@ export function formatUpdatePlan(plan, trust) {
                         : ""}`
                 ]),
             ...(trust === undefined ? [] : formatTrustChange(trust)),
+            ...repairedLines(plan),
             `Schema migrations: ${plan.migrationSteps.length === 0
                 ? "none"
                 : plan.migrationSteps
@@ -146,6 +150,14 @@ export async function runUpdateCommand(options) {
     return okEnvelope("UPDATE_APPLIED", {
         applied: true,
         plan: toPublicUpdatePlan(plan, trust),
-        message: `Managed installation updated to ${plan.targetVersion}.`
+        message: `Managed installation updated to ${plan.targetVersion}.`,
+        ...(plan.installation.repaired.length === 0
+            ? {}
+            : {
+                text: [
+                    `Managed installation updated to ${plan.targetVersion}.`,
+                    ...repairedLines(plan)
+                ].join("\n")
+            })
     });
 }

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

@@ -353,7 +353,7 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
                     ? { action: "continue", status: "UNKNOWN", code: "WORKTREE_GUARD_UNAVAILABLE" }
                     : await evaluateWorktreeWrite(mainRoot, write.paths, write.sessionId, dependencies.worktree === undefined
                         ? undefined
-                        : async (sessionId) => (await ensureSessionWorktree(dependencies.worktree, { cwd: mainRoot, sessionId })).path);
+                        : async (sessionId, agentId) => (await ensureSessionWorktree(dependencies.worktree, { cwd: mainRoot, sessionId, ...(agentId === undefined ? {} : { agentId }) })).path, write.agentId);
             }
             : undefined;
         const worktreeEnter = config.worktree?.mode === "auto"
@@ -361,7 +361,7 @@ 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 evaluateWorktreeEnter(mainRoot, enter.path, enter.sessionId);
+                    : await evaluateWorktreeEnter(mainRoot, enter.path, enter.sessionId, enter.agentId);
             }
             : undefined;
         if (hookEvent === "SessionStart" && config.worktree?.mode === "auto" &&

package/dist/packages/cli/src/public-plan.js

@@ -70,6 +70,7 @@ export function toPublicInstallPlan(plan, trust) {
             ...toPublicOperations(plan.operations),
             ...toPublicPreauthorization(plan.preauthorization)
         ],
+        repaired: plan.repaired,
         detectedVerification: plan.detectedVerification,
         ...(trust === undefined ? {} : { trust })
     };

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

@@ -27,6 +27,10 @@ export function normalizeClaudeHookInput(input) {
     const sessionId = typeof input.session_id === "string"
         ? input.session_id
         : undefined;
+    // Present only inside a subagent, which shares the parent's session_id.
+    const agentId = typeof input.agent_id === "string" && /^[A-Za-z0-9_-]{1,128}$/u.test(input.agent_id)
+        ? input.agent_id
+        : undefined;
     if (input.hook_event_name === "SessionStart") {
         return {
             ...normalizeHookEvent({ event: "session-start", projectRoot }),
@@ -59,7 +63,8 @@ export function normalizeClaudeHookInput(input) {
                 event: "file-write",
                 projectRoot,
                 paths: [resolve(projectRoot, target)],
-                ...(sessionId === undefined ? {} : { sessionId })
+                ...(sessionId === undefined ? {} : { sessionId }),
+                ...(agentId === undefined ? {} : { agentId })
             };
         }
     }
@@ -76,7 +81,8 @@ export function normalizeClaudeHookInput(input) {
                 event: "enter-worktree",
                 projectRoot,
                 path: resolve(projectRoot, target),
-                ...(sessionId === undefined ? {} : { sessionId })
+                ...(sessionId === undefined ? {} : { sessionId }),
+                ...(agentId === undefined ? {} : { agentId })
             };
         }
     }

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

@@ -47,9 +47,11 @@ function parseState(source, sessionId) {
         throw new AgentOpsError("COMPLETION_GATE_STATE_INVALID", "Completion-gate state is invalid.");
     }
     const record = value;
-    const keys = Object.keys(record).filter((key) => key !== "root").sort().join(",");
+    const keys = Object.keys(record).filter((key) => key !== "root" && key !== "extraRoots").sort().join(",");
     if (keys !== "baselineFingerprint,permitFingerprint,schemaVersion,sessionId" ||
         ("root" in record && !validRoot(record.root)) ||
+        ("extraRoots" in record &&
+            (!Array.isArray(record.extraRoots) || record.extraRoots.length > 64 || !record.extraRoots.every(validRoot))) ||
         record.schemaVersion !== 1 ||
         record.sessionId !== sessionId ||
         typeof record.baselineFingerprint !== "string" ||
@@ -253,12 +255,75 @@ export class CompletionGateService {
     }
     async grantPermit(sessionId) {
         const fingerprint = await this.#fingerprint();
-        await this.#store.mutate(sessionId, (state) => {
+        const granted = await this.#store.mutate(sessionId, (state) => {
             if (state === null) {
                 throw new AgentOpsError("COMPLETION_GATE_NOT_INITIALIZED", "The session has no completion-gate baseline.");
             }
             return { ...state, permitFingerprint: fingerprint };
         });
+        // One approved Stop covers every worktree the session works in.
+        if (this.#options.forRoot !== undefined) {
+            for (const root of this.#delegatedRoots(granted)) {
+                if (await isDirectory(root))
+                    await (await this.#options.forRoot(root)).grantPermit(sessionId);
+            }
+        }
+    }
+    /** The worktrees whose gates decide for this session, other than this checkout. */
+    #delegatedRoots(state) {
+        const roots = [...(state.root === undefined ? [] : [state.root]), ...(state.extraRoots ?? [])];
+        return [...new Set(roots)].filter((root) => root !== this.#options.root);
+    }
+    /** Adds a subagent's worktree to the roots this session's Stop must cover. */
+    async addRoot(sessionId, root) {
+        const fingerprint = await this.#fingerprint();
+        await this.#store.mutate(sessionId, (current) => {
+            const base = current ?? {
+                schemaVersion: 1,
+                sessionId,
+                baselineFingerprint: fingerprint,
+                permitFingerprint: null
+            };
+            return { ...base, extraRoots: [...new Set([...(base.extraRoots ?? []), root])] };
+        });
+    }
+    /** Drops one worktree from the session, leaving its other roots in place. */
+    async removeRoot(sessionId, root) {
+        if (await this.#store.read(sessionId) === null)
+            return;
+        await this.#store.mutate(sessionId, (current) => {
+            if (current === null)
+                throw new AgentOpsError("COMPLETION_GATE_NOT_INITIALIZED", "The session baseline disappeared.");
+            const { root: own, extraRoots, ...rest } = current;
+            const remaining = (extraRoots ?? []).filter((candidate) => candidate !== root);
+            return {
+                ...rest,
+                ...(own === undefined || own === root ? {} : { root: own }),
+                ...(remaining.length === 0 ? {} : { extraRoots: remaining })
+            };
+        });
+    }
+    /**
+     * After `worktree finish` merged one worktree: moves the baseline past the
+     * merge and forgets that worktree, keeping the session's other roots.
+     */
+    async afterFinish(sessionId, finishedRoot, baselineFingerprint) {
+        await this.#store.mutate(sessionId, (current) => {
+            const { root: own, extraRoots, ...rest } = current ?? {
+                schemaVersion: 1,
+                sessionId,
+                baselineFingerprint,
+                permitFingerprint: null
+            };
+            const remaining = (extraRoots ?? []).filter((candidate) => candidate !== finishedRoot);
+            return {
+                ...rest,
+                baselineFingerprint,
+                permitFingerprint: null,
+                ...(own === undefined || own === finishedRoot ? {} : { root: own }),
+                ...(remaining.length === 0 ? {} : { extraRoots: remaining })
+            };
+        });
     }
     #isPermitCommand(event) {
         const commands = event.event === "command" ? [event] :
@@ -360,16 +425,24 @@ export class CompletionGateService {
                 : "The session baseline is unavailable: its SessionStart never reached this checkout. The next tool call records one; if this repeats, run agent-ops doctor.");
         }
         const changed = state.baselineFingerprint !== fingerprint && state.permitFingerprint !== fingerprint;
-        if (state.root !== undefined && state.root !== this.#options.root) {
+        const delegated = this.#delegatedRoots(state);
+        if (delegated.length > 0) {
             // This checkout only has to stay untouched; the work, its task and its
-            // evidence live in the worktree, and that gate decides.
+            // evidence live in the worktrees, and each of their gates decides.
             if (changed) {
-                return gateResult("block", "FAIL", "COMPLETION_GATE_MAIN_CHANGED", `This session works in ${state.root}, but this checkout changed too. Move those edits into the worktree, or ask the user for a one-time permit.`);
+                return gateResult("block", "FAIL", "COMPLETION_GATE_MAIN_CHANGED", `This session works in ${delegated.join(", ")}, but this checkout changed too. Move those edits into a worktree, or ask the user for a one-time permit.`);
             }
-            if (!await isDirectory(state.root) || this.#options.forRoot === undefined) {
-                return gateResult("block", "UNKNOWN", "COMPLETION_GATE_WORKTREE_MISSING", `The worktree ${state.root} is unavailable. Run agent-ops worktree list, then resume or remove it.`);
+            let last = null;
+            for (const root of delegated) {
+                if (!await isDirectory(root) || this.#options.forRoot === undefined) {
+                    return gateResult("block", "UNKNOWN", "COMPLETION_GATE_WORKTREE_MISSING", `The worktree ${root} is unavailable. Run agent-ops worktree list, then resume or remove it.`);
+                }
+                const result = await (await this.#options.forRoot(root)).handle(event);
+                if (result !== null && result.action === "block")
+                    return result;
+                last = result;
             }
-            return await (await this.#options.forRoot(state.root)).handle(event);
+            return last;
         }
         if (changed) {
             const failure = await this.#validateTask(sessionId);

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

@@ -5,7 +5,7 @@ import { parseInstallManifest, PROJECT_MANIFEST_PATH } from "../fs/manifest.js";
 import { resolveContainedPath } from "../fs/paths.js";
 import { validateConfig } from "../schema/validate.js";
 import { detectHostRestriction } from "../review/host-sandbox.js";
-import { assertExpectedManagedBlock, assertSupportedManifestOwnership } from "./ownership.js";
+import { assertExpectedManagedBlock, managedBlockBoundariesIntact, assertSupportedManifestOwnership } from "./ownership.js";
 import { isOpencodeManagedPlugin } from "../adapters/opencode/config.js";
 import { harnessDescriptor, managedRules } from "./harness.js";
 import { resolveCapabilities, resolveProfiles } from "./profiles.js";
@@ -214,6 +214,7 @@ async function checkMarkers(root, manifest) {
     }
     const failures = [];
     const legacyPaths = [];
+    const driftedPaths = [];
     const expectedMarkers = assertSupportedManifestOwnership(manifest, root);
     for (const marker of manifest.markers) {
         try {
@@ -229,12 +230,18 @@ async function checkMarkers(root, manifest) {
             }
         }
         catch {
-            failures.push(marker.path);
+            // Intact markers with changed content are repaired by update; broken
+            // boundaries are not, since the owned span cannot be located.
+            const intact = await readContainedText(root, marker.path).then((source) => managedBlockBoundariesIntact(source, marker), () => false);
+            (intact ? driftedPaths : failures).push(marker.path);
         }
     }
     if (failures.length > 0) {
         return check("markers", "FAIL", `Managed block markers failed verification: ${failures.join(", ")}.`, "UPDATE_REQUIRED", "Run `agent-ops update`.");
     }
+    if (driftedPaths.length > 0) {
+        return check("markers", "DEGRADED", `Managed block content changed after installation: ${driftedPaths.join(", ")}.`, "UPDATE_REQUIRED", "Run `agent-ops update`; it rewrites the content between the markers and leaves the rest of the file.");
+    }
     if (legacyPaths.length > 0) {
         return check("markers", "DEGRADED", `Legacy managed routing blocks need migration: ${legacyPaths.join(", ")}.`, "UPDATE_REQUIRED", "Run `agent-ops update`.");
     }

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

@@ -221,12 +221,16 @@ function exactMarkerCount(source, marker) {
     }
     return count;
 }
+/** The start and end markers each appear exactly once, in order. */
+export function managedBlockBoundariesIntact(source, marker) {
+    return (exactMarkerCount(source, marker.startMarker) === 1 &&
+        exactMarkerCount(source, marker.endMarker) === 1 &&
+        source.indexOf(marker.startMarker) < source.indexOf(marker.endMarker));
+}
 export function assertExpectedManagedBlock(source, marker, expected) {
     const startIndex = source.indexOf(marker.startMarker);
     const endIndex = source.indexOf(marker.endMarker);
-    if (exactMarkerCount(source, marker.startMarker) !== 1 ||
-        exactMarkerCount(source, marker.endMarker) !== 1 ||
-        startIndex >= endIndex) {
+    if (!managedBlockBoundariesIntact(source, marker)) {
         throw new AgentOpsError("MANAGED_BLOCK_CHANGED", `Managed block boundaries changed after installation: ${marker.path}`);
     }
     const currentBlock = normalizeToLF(source.slice(startIndex, endIndex + marker.endMarker.length));

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

@@ -7,7 +7,7 @@ import { formatInstallManifest, parseInstallManifest } from "../fs/manifest.js";
 import { AgentOpsError, resolveContainedPath } from "../fs/paths.js";
 import { validateConfig } from "../schema/validate.js";
 import { planHarnessContributions, harnessDescriptor, selectHarnessHookSurface } from "./harness.js";
-import { assertExpectedManagedBlock, assertSupportedManifestOwnership } from "./ownership.js";
+import { assertExpectedManagedBlock, managedBlockBoundariesIntact, assertSupportedManifestOwnership } from "./ownership.js";
 import { codexHooksExplicitlyDisabled, loopLauncherArtifactId, loopSeeds, planLoopContribution, selectedLoopHarnesses } from "./codex-loop.js";
 import { isOpencodeManagedPlugin } from "../adapters/opencode/config.js";
 import { planHookRegistration, planHookRemoval } from "./hooks.js";
@@ -227,13 +227,13 @@ async function planArtifact(root, artifact, existingManifest) {
     if (current !== null && owned === undefined) {
         throw new AgentOpsError("UNMANAGED_INSTALL_PATH", `Refusing to replace an unmanaged install artifact: ${artifact.path}`);
     }
-    if (current !== null &&
-        owned !== undefined &&
-        owned.hash !== current.hash) {
-        throw new AgentOpsError("MANAGED_ARTIFACT_CHANGED", `Managed artifact changed after installation: ${artifact.path}`);
-    }
+    // Drifted managed artifacts are agent-ops owned: rewrite them and report it.
+    const drifted = current !== null && owned !== undefined && owned.hash !== current.hash;
     const hash = sha256(artifact.content);
     return {
+        ...(drifted
+            ? { repaired: { path: artifact.path, reason: "artifact-drift" } }
+            : {}),
         operation: {
             kind: "write",
             path: artifact.path,
@@ -335,6 +335,7 @@ async function planBlocks(root, blocks, removals = [], expectedMarkers = new Map
     }
     const operations = [];
     const records = [];
+    const repaired = [];
     for (const { path, blocks: pathBlocks, removals: pathRemovals } of grouped.values()) {
         const current = await readCurrentFile(root, path);
         if (pathRemovals.length > 0 && current === null) {
@@ -350,6 +351,30 @@ async function planBlocks(root, blocks, removals = [], expectedMarkers = new Map
             content = removeManagedBlock(content, marker.id, expected.markerStyle);
         }
         for (const block of pathBlocks) {
+            const expected = expectedMarkers.get(block.id);
+            if (current !== null && expected !== undefined) {
+                const { start, end } = managedBlockMarkers(block.id, block.version, block.markerStyle);
+                const marker = {
+                    id: block.id,
+                    path,
+                    hash: sha256(content),
+                    owner: "agent-ops",
+                    startMarker: start,
+                    endMarker: end
+                };
+                try {
+                    assertExpectedManagedBlock(content, marker, expected);
+                }
+                catch (error) {
+                    // Content drift is repaired below; broken boundaries stay an error.
+                    if (!managedBlockBoundariesIntact(content, marker)) {
+                        throw error;
+                    }
+                    if (!repaired.some((entry) => entry.path === path)) {
+                        repaired.push({ path, reason: "block-drift" });
+                    }
+                }
+            }
             content = applyManagedBlock(content, block);
         }
         const hash = sha256(content);
@@ -380,7 +405,7 @@ async function planBlocks(root, blocks, removals = [], expectedMarkers = new Map
             });
         }
     }
-    return { operations, records };
+    return { operations, records, repaired };
 }
 export async function createInstallPlan(options) {
     if (options.toolkitVersion !== undefined &&
@@ -498,10 +523,14 @@ export async function createInstallPlan(options) {
     const config = await planConfig(options.root, resolved.profiles, existing?.manifest ?? null, options.existingConfig, options.reviewTargets ?? [], completionGateEnabled, options.worktree);
     operations.push(config.operation);
     artifacts.push(config.record);
+    const repaired = [];
     for (const artifact of contribution.artifacts) {
         const planned = await planArtifact(options.root, artifact, existing?.manifest ?? null);
         operations.push(planned.operation);
         artifacts.push(planned.record);
+        if (planned.repaired !== undefined) {
+            repaired.push(planned.repaired);
+        }
     }
     if (resolved.capabilities.includes("project-loop")) {
         const seedHarnesses = loopHarnessesNeedingSeeds(options.harness, existing?.manifest ?? null);
@@ -513,6 +542,7 @@ export async function createInstallPlan(options) {
     }
     const plannedBlocks = await planBlocks(options.root, contribution.blocks, markersToRemove, expectedExistingMarkers);
     operations.push(...plannedBlocks.operations);
+    repaired.push(...plannedBlocks.repaired);
     const hooks = [];
     if (options.hookRuntimePath !== undefined) {
         for (const harness of options.harness) {
@@ -614,6 +644,7 @@ export async function createInstallPlan(options) {
         config: config.config,
         manifest,
         operations,
+        repaired,
         ...(preauthorization.length === 0 ? {} : { preauthorization }),
         detectedVerification: config.detectedVerification,
         verificationBlockers: config.verificationBlockers

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

@@ -1,14 +1,14 @@
 import { readdir } from "node:fs/promises";
 import { join, relative, sep } from "node:path";
 import { canonicalPath } from "./guard.js";
-import { readWorktreeRecord, WORKTREE_DIRECTORY } from "./service.js";
+import { mayUseWorktree, readWorktreeRecord, WORKTREE_DIRECTORY } from "./service.js";
 /**
  * Whether Claude's EnterWorktree may switch this session into `path`. Only the
  * worktree agent-ops recorded for the session is answered for the host, so an
  * allow never lets the session move its permission root to a directory it did
  * not get from `worktree add`.
  */
-export async function evaluateWorktreeEnter(mainRoot, path, sessionId) {
+export async function evaluateWorktreeEnter(mainRoot, path, sessionId, agentId) {
     if (sessionId === undefined) {
         return { action: "continue", status: "UNKNOWN", code: "WORKTREE_ENTER_UNJUDGED" };
     }
@@ -16,7 +16,8 @@ export async function evaluateWorktreeEnter(mainRoot, path, sessionId) {
     const target = await canonicalPath(path);
     const name = relative(directory, target).split(sep)[0] ?? "";
     const inside = !target.startsWith(`${directory}${sep}`) ? false : target === join(directory, name);
-    if (inside && (await readWorktreeRecord(target))?.sessionId === sessionId) {
+    const entered = inside ? await readWorktreeRecord(target) : null;
+    if (entered !== null && mayUseWorktree(entered, sessionId, agentId)) {
         return {
             action: "continue",
             status: "PASS",
@@ -27,7 +28,8 @@ export async function evaluateWorktreeEnter(mainRoot, path, sessionId) {
     }
     const owned = [];
     for (const entry of await readdir(directory).catch(() => [])) {
-        if ((await readWorktreeRecord(join(directory, entry)))?.sessionId === sessionId) {
+        const record = await readWorktreeRecord(join(directory, entry));
+        if (record !== null && mayUseWorktree(record, sessionId, agentId)) {
             owned.push(join(directory, entry));
         }
     }

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

@@ -319,7 +319,8 @@ export async function finishWorktree(deps, options) {
                 await mainGate.rebase(before, after);
                 // rebase only moves baselines equal to `before`; a main that moved since
                 // this session began would leave it reading the merge as its own change.
-                await mainGate.seed(record.sessionId, after);
+                // Only this worktree leaves the session; its other roots stay covered.
+                await mainGate.afterFinish(record.sessionId, record.path, after);
             });
         }
         await attempt("trust", async () => await deps.trust.revoke(record.path, worktreeConfig));

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

@@ -1,6 +1,6 @@
 import { realpath } from "node:fs/promises";
 import { basename, dirname, join, relative, sep } from "node:path";
-import { insideWorktreeDirectory, readWorktreeRecord, WORKTREE_DIRECTORY } from "./service.js";
+import { insideWorktreeDirectory, mayUseWorktree, readWorktreeRecord, WORKTREE_DIRECTORY } from "./service.js";
 /** The main checkout of the repository `runner` runs in, or null. */
 export async function resolveMainRoot(runner) {
     const result = await runner.run(["rev-parse", "--path-format=absolute", "--git-common-dir"]);
@@ -42,8 +42,10 @@ export async function canonicalPath(path) {
  * business.
  */
 export async function evaluateWorktreeWrite(mainRoot, paths, sessionId, 
-/** Creates or reuses this session's worktree and returns its path. */
-ensureWorktree) {
+/** Creates or reuses this writer's worktree and returns its path. */
+ensureWorktree, 
+/** The subagent making the write, when there is one: it has a worktree of its own. */
+agentId) {
     for (const path of paths) {
         const target = await canonicalPath(path);
         const inMain = target === mainRoot || target.startsWith(`${mainRoot}${sep}`);
@@ -51,17 +53,19 @@ ensureWorktree) {
             // A worktree belongs to the session that made it: writing into another
             // session's mixes two tasks' changes into one review and one merge.
             const name = relative(join(mainRoot, WORKTREE_DIRECTORY), target).split(sep)[0] ?? "";
-            const owner = (await readWorktreeRecord(join(mainRoot, WORKTREE_DIRECTORY, name)))?.sessionId;
-            if (owner !== undefined && owner !== sessionId) {
+            const record = await readWorktreeRecord(join(mainRoot, WORKTREE_DIRECTORY, name));
+            if (record !== null && !mayUseWorktree(record, sessionId, agentId)) {
+                const owner = record.sessionId;
+                const sameSession = owner === sessionId;
                 let own = "";
                 if (ensureWorktree !== undefined) {
-                    own = await ensureWorktree(sessionId).then((worktree) => ` Your own worktree is ${worktree}: edit there instead.`, () => "");
+                    own = await ensureWorktree(sessionId, agentId).then((worktree) => ` Your own worktree is ${worktree}: edit there instead${agentId === undefined ? "" : ", with absolute paths under it"}.`, () => "");
                 }
                 return {
                     action: "block",
                     status: "FAIL",
-                    code: "WORKTREE_OWNED_BY_OTHER_SESSION",
-                    remedy: `${join(mainRoot, WORKTREE_DIRECTORY, name)} belongs to another session (${owner}); ` +
+                    code: sameSession ? "WORKTREE_OWNED_BY_OTHER_AGENT" : "WORKTREE_OWNED_BY_OTHER_SESSION",
+                    remedy: `${join(mainRoot, WORKTREE_DIRECTORY, name)} belongs to ${sameSession ? `another writer of this session (${record.agentId ?? "its main thread"})` : `another session (${owner})`}; ` +
                         `this session is ${sessionId}.${own || " Run agent-ops worktree add <name> --session " + sessionId + " from " + mainRoot + " and edit in the printed path."}`
                 };
             }
@@ -70,12 +74,14 @@ ensureWorktree) {
             let failure = "";
             if (sessionId !== undefined && ensureWorktree !== undefined) {
                 try {
-                    const worktree = await ensureWorktree(sessionId);
+                    const worktree = await ensureWorktree(sessionId, agentId);
                     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}; otherwise use the worktree path as every command's working directory) and redo this edit there, at ${join(worktree, relative(mainRoot, target))}.`
+                        remedy: agentId === undefined
+                            ? `worktree.mode is auto, so this session now has its own worktree at ${worktree}. Enter it (Claude Code: EnterWorktree with path ${worktree}; otherwise use the worktree path as every command's working directory) and redo this edit there, at ${join(worktree, relative(mainRoot, target))}.`
+                            : `worktree.mode is auto, so this subagent now has its own worktree at ${worktree}. Redo this edit there with an absolute path, at ${join(worktree, relative(mainRoot, target))}, and use absolute paths under ${worktree} for every later edit.`
                     };
                 }
                 catch (error) {

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

@@ -149,7 +149,10 @@ export async function resumeWorktree(deps, options) {
     await writeWorktreeRecord(record);
     const mainConfig = await deps.loadConfig(mainRoot);
     if (mainConfig.features.completionGate.enabled && previous.sessionId !== sessionId) {
-        await (await deps.gate(mainRoot, mainConfig)).redirect(previous.sessionId, null);
+        const mainGate = await deps.gate(mainRoot, mainConfig);
+        await (previous.agentId === undefined
+            ? mainGate.redirect(previous.sessionId, null)
+            : mainGate.removeRoot(previous.sessionId, previous.path));
     }
     await bindSession(deps, record, mainConfig, RESUMED_BASELINE);
     return record;
@@ -206,7 +209,10 @@ export async function removeWorktree(deps, options) {
     const { record } = status;
     const mainConfig = await deps.loadConfig(mainRoot);
     if (mainConfig.features.completionGate.enabled) {
-        await (await deps.gate(mainRoot, mainConfig)).redirect(record.sessionId, null);
+        const mainGate = await deps.gate(mainRoot, mainConfig);
+        await (record.agentId === undefined
+            ? mainGate.redirect(record.sessionId, null)
+            : mainGate.removeRoot(record.sessionId, record.path));
     }
     await deps.trust.revoke(record.path, await deps.loadConfig(record.path)).catch(() => undefined);
     await removeCheckout(deps, record, true);

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

@@ -24,6 +24,10 @@ const NAME = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/u;
 const SESSION = /^[^\0\r\n]{1,256}$/u;
 const TARGET_BRANCH = /^[A-Za-z0-9._/-]{1,128}$/u;
 const DEFAULT_SETUP_TIMEOUT_MS = 10 * 60 * 1000;
+/** The session's own worktree is open to its main thread; a subagent's only to that subagent. */
+export function mayUseWorktree(record, sessionId, agentId) {
+    return record.sessionId === sessionId && (agentId === undefined || record.agentId === agentId);
+}
 function worktreeError(code, message) {
     return new AgentOpsError(code, message);
 }
@@ -194,6 +198,7 @@ export async function readWorktreeRecord(root) {
     try {
         const value = JSON.parse(source);
         return value.schemaVersion === 1 && typeof value.name === "string" &&
+            (value.agentId === undefined || typeof value.agentId === "string") &&
             typeof value.branch === "string" && typeof value.path === "string" &&
             typeof value.mainRoot === "string" && typeof value.targetBranch === "string" &&
             typeof value.base === "string" && typeof value.sessionId === "string" &&
@@ -219,7 +224,12 @@ export async function bindSession(deps, record, mainConfig, baselineFingerprint)
         return;
     const worktreeConfig = await deps.loadConfig(record.path);
     await (await deps.gate(record.path, worktreeConfig)).seed(record.sessionId, baselineFingerprint);
-    await (await deps.gate(record.mainRoot, mainConfig)).redirect(record.sessionId, record.path);
+    const mainGate = await deps.gate(record.mainRoot, mainConfig);
+    // A subagent's worktree joins the session's roots instead of replacing its own.
+    if (record.agentId === undefined)
+        await mainGate.redirect(record.sessionId, record.path);
+    else
+        await mainGate.addRoot(record.sessionId, record.path);
 }
 export async function removeCheckout(deps, record, force) {
     await git(deps, record.mainRoot, ["worktree", "remove", ...(force ? ["--force"] : []), record.path], "WORKTREE_REMOVE_FAILED", `Git could not remove ${record.path}.`);
@@ -306,6 +316,7 @@ export async function addWorktree(deps, options) {
         targetBranch,
         base,
         sessionId,
+        ...(options.agentId === undefined ? {} : { agentId: options.agentId }),
         createdAt: deps.now?.() ?? new Date().toISOString()
     };
     let trusted = false;
@@ -336,7 +347,9 @@ export async function addWorktree(deps, options) {
     }
     catch (error) {
         if (mainConfig.features.completionGate.enabled) {
-            await (await deps.gate(mainRoot, mainConfig)).redirect(sessionId, null).catch(() => undefined);
+            const mainGate = await deps.gate(mainRoot, mainConfig);
+            await (options.agentId === undefined ? mainGate.redirect(sessionId, null) : mainGate.removeRoot(sessionId, path))
+                .catch(() => undefined);
         }
         if (trusted)
             await deps.trust.revoke(record.path, mainConfig).catch(() => undefined);
@@ -349,18 +362,31 @@ export function sessionWorktreeName(sessionId) {
     const slug = sessionId.toLowerCase().replace(/[^a-z0-9]/gu, "").slice(0, 8);
     return `session-${slug === "" ? "0" : slug}`;
 }
+/** The session's worktree name plus the first eight name-safe characters of the subagent id. */
+export function agentWorktreeName(sessionId, agentId) {
+    const slug = agentId.toLowerCase().replace(/[^a-z0-9]/gu, "").slice(0, 8);
+    return `${sessionWorktreeName(sessionId)}-${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.
+ * The worktree `sessionId` (or one of its subagents) works in, created on
+ * first use. One already bound to the same session and agent is reused, so a
+ * writer 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 { agentId } = options;
+    const name = agentId === undefined
+        ? sessionWorktreeName(options.sessionId)
+        : agentWorktreeName(options.sessionId, agentId);
     const existing = await readWorktreeRecord(worktreePath(mainRoot, name));
-    if (existing?.sessionId === options.sessionId)
+    if (existing?.sessionId === options.sessionId && existing.agentId === agentId)
         return existing;
-    return (await addWorktree(deps, { cwd: mainRoot, name, sessionId: options.sessionId })).record;
+    return (await addWorktree(deps, {
+        cwd: mainRoot,
+        name,
+        sessionId: options.sessionId,
+        ...(agentId === undefined ? {} : { agentId })
+    })).record;
 }
 function sessionOriginPath(mainRoot, sessionId) {
     return join(mainRoot, ".agent-ops", "tasks", "session-origin", sha256(sessionId));

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

@@ -0,0 +1,84 @@
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { AgentOpsError } from "../fs/paths.js";
+import { ReviewInterruptedError } from "./execute.js";
+/** Reviews allowed at once across every worktree of a repository. */
+export const REVIEW_SLOT_WIDTH = 2;
+const POLL_MS = 1000;
+// A review is two reviewer sessions of at most 15 minutes each plus probes.
+const STALE_MS = 2 * 60 * 60 * 1000;
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+// ponytail: same scheme as withFinishLock in parallel/finish.ts; unify if a third user appears.
+async function stale(path, staleMs) {
+    try {
+        const owner = JSON.parse(await readFile(join(path, "owner.json"), "utf8"));
+        if (typeof owner.pid !== "number" || typeof owner.at !== "number")
+            return true;
+        return !alive(owner.pid) || Date.now() - owner.at > staleMs;
+    }
+    catch {
+        // A holder between mkdir and writing its owner file looks like this too.
+        try {
+            return Date.now() - (await stat(path)).mtimeMs > 60_000;
+        }
+        catch {
+            return true;
+        }
+    }
+}
+/**
+ * Runs `action` once one of `width` shared slots is free. Reviewer CLIs are
+ * metered and flaky under load, and writers in separate worktrees each start
+ * their own review, so this is what keeps the total bounded. A slot held by a
+ * dead process is reclaimed.
+ */
+export async function withReviewSlot(options, action) {
+    const width = options.width ?? REVIEW_SLOT_WIDTH;
+    if (!Number.isInteger(width) || width < 1) {
+        throw new AgentOpsError("REVIEW_SLOT_INVALID_WIDTH", "Review slot width must be a positive integer.");
+    }
+    const sleep = options.sleep ?? (async (ms) => await new Promise((resolve) => setTimeout(resolve, ms)));
+    let waiting = false;
+    let held;
+    while (held === undefined) {
+        if (options.signal?.aborted === true)
+            throw new ReviewInterruptedError(String(options.signal.reason ?? ""));
+        for (let index = 0; index < width && held === undefined; index += 1) {
+            const path = join(options.dir, `agent-ops-review-slot-${index}.lock`);
+            try {
+                await mkdir(path);
+                await writeFile(join(path, "owner.json"), JSON.stringify({ pid: process.pid, at: Date.now() }));
+                held = path;
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                if (await stale(path, options.staleMs ?? STALE_MS)) {
+                    await rm(path, { recursive: true, force: true });
+                    index -= 1; // try the reclaimed slot again at once
+                }
+            }
+        }
+        if (held === undefined) {
+            if (!waiting) {
+                waiting = true;
+                options.onWait?.(`review: waiting for one of ${String(width)} shared review slots`);
+            }
+            await sleep(options.pollMs ?? POLL_MS);
+        }
+    }
+    try {
+        return await action();
+    }
+    finally {
+        await rm(held, { recursive: true, force: true });
+    }
+}

package/docs/en/spec/delegation.md

@@ -39,3 +39,13 @@ Parallel editing conversations in one repository MUST each work in their own age
 - Evidence: `agent-ops worktree list` shows one worktree per editing session, and each finish reports a fast-forward merge.
 - Positive: `Two conversations edit .worktrees/login and .worktrees/cart; each verifies, reviews and finishes on its own.`
 - Negative: `Two conversations edit the main checkout at once, so each one's verification and review is voided by the other's writes.`
+
+## DELEGATE-ISOLATION-003
+
+Subagents that write files in one session MUST each work in their own agent-ops worktree, with their own task, verification and review.
+
+- Trigger: `worktree.mode` is `auto` and a subagent writes a file. Hook calls made inside a subagent carry its `agent_id` under the parent's `session_id`; a payload without `agent_id` is treated as the session's main thread.
+- Action: The first blocked write allocates a worktree owned by that session and agent; edit there using absolute paths, because the hook's `cwd` does not follow a `cd`. The subagent commits and runs `agent-ops verify` and `agent-ops review` in its worktree. At most two reviews run at once across all worktrees of the repository; the rest wait. The coordinator runs `agent-ops worktree finish <name>` for each worktree in turn, and Stop is allowed only when every worktree of the session has a completed task.
+- Evidence: `agent-ops worktree list` shows an `agent:` line for each subagent worktree, writing into another writer's worktree is refused with `WORKTREE_OWNED_BY_OTHER_AGENT`, and each finish reports a fast-forward merge.
+- Positive: `Two subagents implement independent tasks in .worktrees/session-ab12cd34-a9230363 and .worktrees/session-ab12cd34-b1111111; each reviews itself and the coordinator finishes them one after the other.`
+- Negative: `A subagent edits the coordinator's worktree, or two subagents edit one worktree, so one review covers two tasks' changes.`

package/docs/en/spec/maintenance.md

@@ -30,3 +30,13 @@ hand-edited in place.
 - Evidence: The artifact hash and shim import tests pass; release documentation records the revalidation condition.
 - Positive: `agent-ops update` rewrites a changed plugin after ownership checks pass.
 - Negative: `Patch the opencode plugin manually and retain the old manifest hash.`
+
+## MAINTAIN-DRIFT-001
+
+`agent-ops update` MUST rewrite a managed artifact or managed block whose content drifted from the manifest, MUST report each rewrite, and MUST NOT rewrite anything it cannot prove it owns.
+
+- Trigger: `agent-ops update` finds a managed whole-file artifact whose hash differs from the manifest, or a managed block whose markers are intact but whose content changed, for example after a Git operation restored an older tracked revision.
+- Action: Rewrite the artifact, or only the content between the markers, and list it as `repaired: <path> (<reason>)`. Keep `.agent-ops/config.json`, `agent-ops uninstall`, paths absent from the manifest, and blocks with missing, duplicated or reordered markers as errors; the last needs a person to locate the owned span.
+- Evidence: `InstallPlan.repaired` and the update output name each rewritten path; text outside the markers is byte-identical afterwards.
+- Positive: `A tracked .agent-ops/GEMINI.md restored to an older version is rewritten by update, with "repaired: .agent-ops/GEMINI.md (artifact drift)".`
+- Negative: `Rewrite a block whose end marker was deleted, or overwrite .agent-ops/config.json.`

package/docs/en/spec/troubleshooting.md

@@ -19,3 +19,13 @@ The operator MUST preserve the failing evidence before applying a fix.
 - Evidence: The test fails before the fix and passes after it.
 - Positive: `RED parser test → GREEN parser test.`
 - Negative: `Delete the failing test because it is inconvenient.`
+
+## TROUBLESHOOT-DRIFT-001
+
+An update that reports `repaired:` lines or a doctor check that reports drift MUST be read as managed content that no longer matched the manifest, not as a failed update.
+
+- Trigger: `agent-ops doctor` reports `UPDATE_REQUIRED` for managed artifacts or DEGRADED managed blocks, or `agent-ops update` prints `repaired: <path> (<reason>)`.
+- Action: Run `agent-ops update`. It rewrites a drifted managed artifact or the content between intact block markers. It still fails on `.agent-ops/config.json`, `agent-ops uninstall`, paths absent from the manifest, and blocks with missing, duplicated or reordered markers; fix those by hand, then update again. See MAINTAIN-DRIFT-001.
+- Evidence: The update output names each repaired path and a second `agent-ops doctor` reports no drift.
+- Positive: `A restored older GEMINI.md is rewritten and listed as "repaired: .agent-ops/GEMINI.md (artifact drift)".`
+- Negative: `Delete the manifest to silence MANAGED_BLOCK_CHANGED on a block whose end marker is missing.`

package/docs/zh-TW/spec/delegation.md

@@ -41,3 +41,13 @@ English source version: 2026-09-24. Revalidate: when the English specification c
 - Evidence: `agent-ops worktree list` 顯示每個修改中的 session 各有一個 worktree，且每次 finish 都回報 fast-forward 合併。
 - Positive: `兩個對話分別修改 .worktrees/login 與 .worktrees/cart；各自驗證、review 並 finish。`
 - Negative: `兩個對話同時修改主 checkout，彼此的寫入讓對方的驗證與 review 全部作廢。`
+
+## DELEGATE-ISOLATION-003
+
+同一個 session 中會寫入檔案的 subagent MUST 各自在自己的 agent-ops worktree 中工作，並各自擁有 task、驗證與 review。
+
+- Trigger: `worktree.mode` 為 `auto`，且 subagent 寫入檔案。subagent 內的 hook 呼叫會在父對話的 `session_id` 之下帶有自己的 `agent_id`；沒有 `agent_id` 的 payload 視為該 session 的主執行緒。
+- Action: 第一次被擋下的寫入會配發一個屬於該 session 與該 agent 的 worktree；之後用絕對路徑在那裡編輯，因為 hook 的 `cwd` 不會跟著 `cd` 改變。subagent 在自己的 worktree 內 commit，並執行 `agent-ops verify` 與 `agent-ops review`。整個 repository 的所有 worktree 同時最多進行兩個 review，其餘排隊等待。協調者依序對每個 worktree 執行 `agent-ops worktree finish <name>`；只有該 session 的每個 worktree 都有已完成的 task，Stop 才會放行。
+- Evidence: `agent-ops worktree list` 為每個 subagent worktree 顯示一行 `agent:`，寫入其他 writer 的 worktree 會以 `WORKTREE_OWNED_BY_OTHER_AGENT` 被拒絕，且每次 finish 都回報 fast-forward 合併。
+- Positive: `兩個 subagent 在 .worktrees/session-ab12cd34-a9230363 與 .worktrees/session-ab12cd34-b1111111 各自實作獨立的 task；各自 review，協調者依序 finish。`
+- Negative: `subagent 修改協調者的 worktree，或兩個 subagent 修改同一個 worktree，導致一次 review 涵蓋兩個 task 的變更。`

package/docs/zh-TW/spec/maintenance.md

@@ -31,3 +31,13 @@ English source version: 2026-07-31. Revalidate: when the English specification c
 - Evidence: artifact hash 與 shim import 測試通過；release 文件記錄重驗條件。
 - Positive: `agent-ops update` 通過 ownership checks 後重寫已變更的 plugin。
 - Negative: `手動修改 .opencode/plugins/agent-ops.js，卻保留舊的 manifest hash。`
+
+## MAINTAIN-DRIFT-001
+
+`agent-ops update` MUST 重寫內容已偏離 manifest 的 managed artifact 或 managed block，MUST 回報每一次重寫，且 MUST NOT 重寫無法證明歸其所有的內容。
+
+- Trigger: `agent-ops update` 發現 managed 整檔 artifact 的 hash 與 manifest 不同，或 managed block 的標記完整但內容已變更，例如 Git 操作把已追蹤檔案還原成舊版。
+- Action: 重寫該 artifact，或只重寫標記之間的內容，並以 `repaired: <path> (<reason>)` 列出。`.agent-ops/config.json`、`agent-ops uninstall`、不在 manifest 內的路徑，以及標記缺失、重複或順序顛倒的 block 仍視為錯誤；最後一種需要人來判斷哪一段歸 agent-ops。
+- Evidence: `InstallPlan.repaired` 與 update 輸出列出每個被重寫的路徑；標記以外的文字前後逐位元組相同。
+- Positive: `被還原成舊版的已追蹤 .agent-ops/GEMINI.md 由 update 重寫，並輸出 "repaired: .agent-ops/GEMINI.md (artifact drift)"。`
+- Negative: `重寫結束標記已被刪除的 block，或覆寫 .agent-ops/config.json。`

package/docs/zh-TW/spec/troubleshooting.md

@@ -21,3 +21,13 @@ English source version: 2026-07-23. Revalidate: when the English specification c
 - Evidence: 測試在修正前失敗、修正後通過。
 - Positive: `RED parser test → GREEN parser test。`
 - Negative: `因為不方便就刪除失敗測試。`
+
+## TROUBLESHOOT-DRIFT-001
+
+update 輸出 `repaired:` 行，或 doctor 回報漂移時，MUST 視為 managed 內容與 manifest 不符，而不是 update 失敗。
+
+- Trigger: `agent-ops doctor` 對 managed artifact 回報 `UPDATE_REQUIRED`，或對 managed block 回報 DEGRADED，或 `agent-ops update` 輸出 `repaired: <path> (<reason>)`。
+- Action: 執行 `agent-ops update`。它會重寫已漂移的 managed artifact，或標記完整的 block 標記之間的內容。`.agent-ops/config.json`、`agent-ops uninstall`、不在 manifest 內的路徑，以及標記缺失、重複或順序顛倒的 block 仍會失敗；這些要手動修正後再 update。見 MAINTAIN-DRIFT-001。
+- Evidence: update 輸出列出每個被修復的路徑，且再跑一次 `agent-ops doctor` 不再回報漂移。
+- Positive: `被還原的舊版 GEMINI.md 被重寫，並列出 "repaired: .agent-ops/GEMINI.md (artifact drift)"。`
+- Negative: `為了消除結束標記缺失的 MANAGED_BLOCK_CHANGED 而刪除 manifest。`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kylecheng3146/agent-ops",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Evidence-driven development loops for agy, Codex, Claude Code, and opencode",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",