@kylecheng3146/agent-ops 0.4.1 → 0.5.1

package/LICENSE

@@ -1,21 +1,91 @@
-MIT License
-
-Copyright (c) 2026 Kyle Cheng
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Required Notice: Copyright (c) 2026 Kyle Cheng (https://github.com/kylecheng3146/agent-ops)
+
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any product that competes with the software or any product the licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality through different kinds of interfaces or for different technical platforms.  Applications can compete with services, libraries with plugins, frameworks with development tools, and so on, even if they're written in different programming languages or for different computer architectures.  Goods and services compete even when provided free of charge.  If you market a product as a practical substitute for the software or another product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does not compete, but the licensor or any of its affiliates brings your product into competition by providing a new version of the software or another product using the software, you may continue using versions of the software available under these terms beforehand to provide your competing product, but not any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product or service that the licensor or any of its affiliates has stopped providing, unless the licensor includes a plain-text line beginning with `Licensor Line of Business:` with the software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of business developing the software or using the software to provide a product, the buyer can also enforce [Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+A **product** can be a good or service, or a combination of them.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all its affiliates.
+
+**Affiliates** means the other organizations than an organization has control over, is under the control of, or is under common control with.
+
+**Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -412,4 +412,7 @@ Documentation:
 
 ## License
 
-Copyright (c) 2026 Kyle Cheng. Released under the [MIT License](LICENSE).
+Copyright (c) 2026 Kyle Cheng. Released under the
+[PolyForm Shield License 1.0.0](LICENSE): free to use, change and share,
+including inside a company, but not to build a product or service that competes
+with agent-ops. Versions up to 0.4.1 were released under, and remain under, the MIT License.

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/install/preauth.js

@@ -17,14 +17,26 @@ export const CLAUDE_PREAUTH_ALLOW = [
     "Bash(agent-ops review *)",
     "Bash(agent-ops batch *)",
     "Bash(agent-ops worktree *)",
-    "Bash(agent-ops doctor *)"
+    "Bash(agent-ops doctor *)",
+    // The PreToolUse hook still blocks a path this session does not own.
+    "EnterWorktree",
+    // A worktree commit runs the project's pre-commit hook, usually this.
+    "Bash(npx lint-staged *)"
 ];
-/** review and batch talk to the reviewer's API, which the sandbox withholds. */
+/**
+ * review and batch talk to the reviewer's API, which the sandbox withholds;
+ * worktree commit and lint-staged write the main .git, which a worktree's
+ * sandbox cannot.
+ */
 export const CLAUDE_PREAUTH_UNSANDBOXED = [
     "agent-ops review",
     "agent-ops review *",
     "agent-ops batch",
-    "agent-ops batch *"
+    "agent-ops batch *",
+    "agent-ops worktree commit",
+    "agent-ops worktree commit *",
+    "npx lint-staged",
+    "npx lint-staged *"
 ];
 export const CODEX_RULES_PATH = "rules/agent-ops.rules";
 export const CODEX_RULES_MARKER = "# agent-ops managed: regenerated by agent-ops init and update; do not edit.";
@@ -60,6 +72,26 @@ function rule(options) {
  */
 export const CODEX_RULES_CONTENT = `${[
     CODEX_RULES_MARKER,
+    ...[
+        {
+            pattern: ["agent-ops", "worktree", "commit"],
+            justification: "agent-ops worktree commit runs git hooks, which write the main .git outside the sandbox.",
+            match: "agent-ops worktree commit -m message"
+        },
+        {
+            pattern: ["npx", "lint-staged"],
+            justification: "lint-staged backs up through the main .git, which the sandbox cannot write from a worktree.",
+            match: "npx lint-staged --debug"
+        }
+    ].map((entry) => [
+        "prefix_rule(",
+        `    pattern = ${starlarkList(entry.pattern)},`,
+        '    decision = "allow",',
+        `    justification = ${JSON.stringify(entry.justification)},`,
+        `    match = [${JSON.stringify(entry.match)}],`,
+        '    not_match = ["agent-ops trust grant --scope project --yes"]',
+        ")"
+    ].join("\n")),
     ...[true, false].flatMap((withHost) => {
         const host = withHost ? "AGENT_OPS_HOST=codex " : "";
         const env = `env -u CODEX_SANDBOX_NETWORK_DISABLED ${host}agent-ops`;
@@ -240,7 +272,7 @@ async function codexChange(codexHome, desired) {
                 content: CODEX_RULES_CONTENT,
                 expectedHash: current?.hash ?? null
             },
-            summary: `Writes ${join(codexHome, CODEX_RULES_PATH)}: allow rules for agent-ops review and doctor --check-auth.`,
+            summary: `Writes ${join(codexHome, CODEX_RULES_PATH)}: allow rules for agent-ops review, batch, doctor --check-auth, worktree commit and lint-staged.`,
             ownedContent: true
         };
 }

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/guides/configuration.md

@@ -236,12 +236,15 @@ evidence. Give each editing conversation its own worktree instead:
 - With `worktree.mode` auto, `init` and `update` also pre-authorize what a
   session runs itself, and the plan lists it before you confirm: in
   `.claude/settings.local.json`, `permissions.allow` for `agent-ops task`,
-  `verify`, `review`, `worktree` and `doctor` and `sandbox.excludedCommands`
-  for `agent-ops review` (your other entries are kept, and the plan describes
+  `verify`, `review`, `worktree` and `doctor`, plus `EnterWorktree` (the hook
+  still blocks a path the session does not own) and `npx lint-staged`, and
+  `sandbox.excludedCommands` for `agent-ops review`, `batch`, `worktree commit`
+  and `npx lint-staged` (your other entries are kept, and the plan describes
   the file instead of printing it); and, when the CLI can see Codex's home
   (`CODEX_HOME`, else `~/.codex`), `rules/agent-ops.rules` with allow rules
   for `agent-ops review` and `doctor --check-auth`, with and without
-  `AGENT_OPS_HOST=`. `trust`, `allow-stop`, `init`, `update` and `uninstall`
+  `AGENT_OPS_HOST=`, and for `agent-ops worktree commit` and `npx lint-staged`,
+  so a pre-commit hook can write the main `.git`. `trust`, `allow-stop`, `init`, `update` and `uninstall`
   are never pre-authorized. Turning auto mode off, or `uninstall`, takes
   exactly those entries back out; a rules file of that name agent-ops did not
   write is left alone.

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/guides/configuration.md

@@ -204,11 +204,14 @@ fingerprint，因此兩個對話修改同一個 checkout 會互相作廢對方
   會把較舊的 matcher 回報為註冊漂移。
 - 當 `worktree.mode` 為 auto，`init` 與 `update` 也會預先授權 session 自己會執行的
   指令，並在你確認前先列在計畫裡：在 `.claude/settings.local.json` 寫入
-  `agent-ops task`、`verify`、`review`、`worktree`、`doctor` 的 `permissions.allow`，
-  以及 `agent-ops review` 的 `sandbox.excludedCommands`（你原有的項目會保留，計畫只
-  描述該檔案而不印出內容）；若 CLI 找得到 Codex 的 home（`CODEX_HOME`，否則
-  `~/.codex`），另寫入 `rules/agent-ops.rules`，內含 `agent-ops review` 與
-  `doctor --check-auth` 的 allow 規則（含與不含 `AGENT_OPS_HOST=`）。`trust`、
+  `agent-ops task`、`verify`、`review`、`worktree`、`doctor`，加上 `EnterWorktree`
+  （hook 仍會擋下 session 不擁有的路徑）與 `npx lint-staged` 的 `permissions.allow`，
+  以及 `agent-ops review`、`batch`、`worktree commit` 與 `npx lint-staged` 的
+  `sandbox.excludedCommands`（你原有的項目會保留，計畫只描述該檔案而不印出內容）；
+  若 CLI 找得到 Codex 的 home（`CODEX_HOME`，否則 `~/.codex`），另寫入
+  `rules/agent-ops.rules`，內含 `agent-ops review` 與 `doctor --check-auth` 的 allow
+  規則（含與不含 `AGENT_OPS_HOST=`），以及 `agent-ops worktree commit` 與
+  `npx lint-staged` 的 allow 規則，讓 pre-commit hook 能寫入主 `.git`。`trust`、
   `allow-stop`、`init`、`update`、`uninstall` 永遠不會被預先授權。關閉 auto 模式或
   `uninstall` 會精確移除這些項目；同名但不是 agent-ops 寫的規則檔不會被動到。
 - `review` 與 `doctor` 支援 `--output <file>`：JSON envelope 寫入該檔（權限 0600），

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,9 +1,9 @@
 {
   "name": "@kylecheng3146/agent-ops",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Evidence-driven development loops for agy, Codex, Claude Code, and opencode",
   "type": "module",
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
   "repository": "github:kylecheng3146/agent-ops",
   "engines": {
     "node": ">=22.14.0"