@kylecheng3146/agent-ops 0.3.1 → 0.3.3

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

@@ -86,6 +86,7 @@ export function parseArgs(argv) {
     let versionSeen = false;
     let worktreeName;
     let force = false;
+    let worktree;
     for (let index = 0; index < argv.length; index += 1) {
         const token = argv[index];
         if (token === undefined) {
@@ -229,6 +230,18 @@ export function parseArgs(argv) {
                 }
                 completionGate = true;
                 break;
+            case "--worktree": {
+                if (worktree !== undefined) {
+                    duplicate(token);
+                }
+                const value = readOptionValue(argv, index, token);
+                if (value !== "auto" && value !== "off") {
+                    throw new CliArgumentError("CLI_INVALID_VALUE", `Worktree mode must be auto or off: ${value}`, token);
+                }
+                worktree = value;
+                index += 1;
+                break;
+            }
             case "--dry-run":
                 if (dryRun) {
                     duplicate(token);
@@ -367,6 +380,7 @@ export function parseArgs(argv) {
             dryRun ||
             yes ||
             rerun ||
+            worktree !== undefined ||
             force) {
             throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Only --json may be combined with global help or version.");
         }
@@ -432,6 +446,9 @@ export function parseArgs(argv) {
     if (completionGate !== undefined && command !== "init") {
         throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--completion-gate may be used only with init.");
     }
+    if (worktree !== undefined && command !== "init" && command !== "update") {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--worktree may be used only with init or update.");
+    }
     if (command === "task") {
         if (harness !== undefined ||
             profiles.length > 0 ||
@@ -551,6 +568,7 @@ export function parseArgs(argv) {
         rerun,
         dryRun,
         json,
-        yes
+        yes,
+        ...(worktree === undefined ? {} : { worktree })
     };
 }

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

@@ -348,6 +348,7 @@ else {
                         trustStore: store,
                         calculateTrustBinding: async (config) => await plannedTrustBinding(root, config),
                         confirm: async (plan, trust) => await confirmPlan(formatUpdatePlan(plan, trust)),
+                        promptWorktree: async (message) => await selectYesNo(message, { input: process.stdin, output: process.stdout }, true),
                         ...(updateArgs.targetVersion === undefined
                             ? {}
                             : { targetVersion: updateArgs.targetVersion })

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

@@ -39,6 +39,7 @@ Options:
   --profile <core|advisory|guardrails|loop>  Repeatable
   --review-target <codex|agy|claude>  Repeatable init option; review pair order
   --completion-gate                  Init only: enable the project-loop completion gate
+  --worktree <auto|off>              Init/update: configure session worktree isolation
   --check-auth                        Doctor only: probe selected review targets'
                                       authentication with one real call
   --check-auth-target <target>        Repeatable doctor filter with --check-auth
@@ -75,6 +76,7 @@ Options:
   --profile <core|advisory|guardrails|loop>  Repeatable
   --review-target <codex|agy|claude>   Repeatable, in fallback-chain order
   --completion-gate                    Enable the project-loop completion gate
+  --worktree <auto|off>                Configure session worktree isolation
   --dry-run                            Print the plan without writing
   --json
   --yes
@@ -114,6 +116,7 @@ Options:
   --scope <project|user>
   --harness <all|both|agy|claude|codex|opencode|comma-separated>
   --target-version <version>   Offline-capable update target
+  --worktree <auto|off>        Configure session worktree isolation
   --dry-run
   --json
   --yes

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

@@ -5,6 +5,7 @@ import { okEnvelope } from "../output.js";
 import { formatOperationPlan } from "../plan-output.js";
 import { toPublicInstallPlan } from "../public-plan.js";
 import { formatTrustChange, planTrustGrant } from "./trust.js";
+import { checkWorktreeEnvWarning, detectWorktreeSetup } from "../../../../runtime/src/install/parallel-setup.js";
 export function formatInstallPlan(plan, trust, warnings = []) {
     const hooks = plan.manifest.hooks ?? [];
     const detectedVerification = plan.detectedVerification;
@@ -14,6 +15,13 @@ export function formatInstallPlan(plan, trust, warnings = []) {
             `Scope: ${plan.scope}`,
             `Harness: ${plan.harness}`,
             `Profiles: ${plan.profiles.join(", ")}`,
+            ...(plan.config.worktree === undefined
+                ? []
+                : [
+                    `Worktree: mode=${plan.config.worktree.mode}${plan.config.worktree.setup && plan.config.worktree.setup.length > 0
+                        ? `, setup=${plan.config.worktree.setup.map((s) => `${s.command} ${s.args.join(" ")}`.trim()).join("; ")}`
+                        : ""}`
+                ]),
             ...(plan.scope === "user" && plan.harness.includes("agy")
                 ? ["Notice: .gemini/GEMINI.md is a shared Gemini rule surface."]
                 : []),
@@ -85,6 +93,11 @@ export async function runInitCommand(options) {
         args.profiles.length === 0) {
         throw new AgentOpsError("INIT_CHOICES_REQUIRED", "Init requires complete scope, harness, and profile choices.");
     }
+    const worktreeConfig = args.worktree === "auto"
+        ? { mode: "auto", setup: await detectWorktreeSetup(options.root) }
+        : args.worktree === "off"
+            ? { mode: "off" }
+            : undefined;
     const plan = await createInstallPlan({
         root: options.root,
         scope: args.scope,
@@ -105,7 +118,10 @@ export async function runInitCommand(options) {
             : { reviewTargets: args.reviewTargets }),
         ...(args.completionGate === undefined
             ? {}
-            : { completionGateEnabled: args.completionGate })
+            : { completionGateEnabled: args.completionGate }),
+        ...(worktreeConfig === undefined
+            ? {}
+            : { worktree: worktreeConfig })
     });
     const trust = await trustChange(options, plan);
     // An installation with no verifier looks finished and is not: every task
@@ -121,7 +137,14 @@ export async function runInitCommand(options) {
                     : ` Detection stopped because — ${plan.verificationBlockers.join("; ")}`)
         ]
         : [];
-    const warnings = [...verificationWarnings, ...(plan.harness.includes("agy") && options.agyWarning !== undefined
+    const worktreeEnvWarning = plan.config.worktree?.mode === "auto"
+        ? await checkWorktreeEnvWarning(options.root)
+        : undefined;
+    const worktreeWarnings = worktreeEnvWarning === undefined ? [] : [worktreeEnvWarning];
+    const warnings = [
+        ...verificationWarnings,
+        ...worktreeWarnings,
+        ...(plan.harness.includes("agy") && options.agyWarning !== undefined
             ? (() => {
                 try {
                     const warning = options.agyWarning();
@@ -131,7 +154,8 @@ export async function runInitCommand(options) {
                     return ["agy could not be probed; run `agent-ops doctor` to verify it."];
                 }
             })()
-            : [])];
+            : [])
+    ];
     if (args.dryRun) {
         return okEnvelope("INIT_PLAN_READY", {
             applied: false,

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

@@ -1,3 +1,6 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { detectWorktreeSetup } from "../../../../runtime/src/install/parallel-setup.js";
 import { applyUpdatePlan, createUpdatePlan } from "../../../../runtime/src/install/update.js";
 import { okEnvelope } from "../output.js";
 import { formatOperationPlan } from "../plan-output.js";
@@ -10,6 +13,13 @@ export function formatUpdatePlan(plan, trust) {
         metadata: [
             `Target version: ${plan.targetVersion}`,
             `Harness: ${plan.installation.harness.join(", ")}`,
+            ...(plan.installation.config.worktree === undefined
+                ? []
+                : [
+                    `Worktree: mode=${plan.installation.config.worktree.mode}${plan.installation.config.worktree.setup && plan.installation.config.worktree.setup.length > 0
+                        ? `, setup=${plan.installation.config.worktree.setup.map((s) => `${s.command} ${s.args.join(" ")}`.trim()).join("; ")}`
+                        : ""}`
+                ]),
             ...(trust === undefined ? [] : formatTrustChange(trust)),
             `Schema migrations: ${plan.migrationSteps.length === 0
                 ? "none"
@@ -47,7 +57,40 @@ async function trustChange(options, plan) {
         ? { action: "skipped", reason: "no-verification-commands" }
         : await planTrustGrant(binding, options.trustStore);
 }
+async function existingConfigHasWorktree(root) {
+    try {
+        const content = await readFile(join(root, ".agent-ops", "config.json"), "utf8");
+        const parsed = JSON.parse(content);
+        return parsed.worktree !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
 export async function runUpdateCommand(options) {
+    let worktree;
+    if (options.args.worktree === "auto") {
+        worktree = {
+            mode: "auto",
+            setup: await detectWorktreeSetup(options.root)
+        };
+    }
+    else if (options.args.worktree === "off") {
+        worktree = { mode: "off" };
+    }
+    else if (options.args.worktree === undefined &&
+        options.promptWorktree !== undefined &&
+        options.isTTY &&
+        !options.args.yes &&
+        !(await existingConfigHasWorktree(options.root))) {
+        const shouldEnable = await options.promptWorktree("Enable Git worktree isolation for parallel agent sessions?");
+        if (shouldEnable) {
+            worktree = {
+                mode: "auto",
+                setup: await detectWorktreeSetup(options.root)
+            };
+        }
+    }
     const plan = await createUpdatePlan({
         root: options.root,
         adapters: options.adapters,
@@ -57,9 +100,9 @@ export async function runUpdateCommand(options) {
         ...(options.registry === undefined
             ? {}
             : { registry: options.registry }),
-        ...(options.targetVersion === undefined
+        ...((options.targetVersion ?? options.args.targetVersion) === undefined
             ? {}
-            : { targetVersion: options.targetVersion }),
+            : { targetVersion: options.targetVersion ?? options.args.targetVersion }),
         ...(options.toolkitVersion === undefined
             ? {}
             : { toolkitVersion: options.toolkitVersion }),
@@ -68,7 +111,8 @@ export async function runUpdateCommand(options) {
             : { hookRuntimePath: options.hookRuntimePath }),
         ...((options.hookTargets ?? options.args.hookTargets) === undefined
             ? {}
-            : { hookTargets: options.hookTargets ?? options.args.hookTargets })
+            : { hookTargets: options.hookTargets ?? options.args.hookTargets }),
+        ...(worktree === undefined ? {} : { worktree })
     });
     const trust = await trustChange(options, plan);
     if (options.args.dryRun) {

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

@@ -193,6 +193,20 @@ export async function completeInitChoices(args, io, setup = {}) {
         const reviewTargets = args.reviewTargets ?? (enabled && eligibleReviewChoices.length > 0
             ? await selectOptions("Review targets (multi-select: tried in listed order)", eligibleReviewChoices, selectorIo, REVIEW_TARGET_ORDER.filter((target) => harness.includes(target)), { startEmpty: true })
             : []);
+        const worktree = args.worktree ?? (scope === "project"
+            ? (await selectOption("Enable Git worktree isolation for parallel agent sessions?", [
+                {
+                    label: "yes",
+                    value: "auto",
+                    description: "Recommended. Isolates each agent session in a dedicated worktree."
+                },
+                {
+                    label: "no",
+                    value: "off",
+                    description: "Keep a single shared checkout."
+                }
+            ], selectorIo))
+            : undefined);
         await probeReviewTargets(reviewTargets, setup);
         return {
             ...args,
@@ -200,7 +214,8 @@ export async function completeInitChoices(args, io, setup = {}) {
             harness,
             profiles,
             ...(completionGate ? { completionGate: true } : {}),
-            ...(reviewTargets.length === 0 ? {} : { reviewTargets })
+            ...(reviewTargets.length === 0 ? {} : { reviewTargets }),
+            ...(worktree !== undefined ? { worktree } : {})
         };
     }
     const session = await createPromptSession(io);
@@ -220,13 +235,17 @@ export async function completeInitChoices(args, io, setup = {}) {
             ? selectReviewTargets(await session.question(`Review targets (${defaultReviewTargets.join(",") || "none"}): `), defaultReviewTargets)
             : []);
         await probeReviewTargets(reviewTargets, setup);
+        const worktree = args.worktree ?? (scope === "project"
+            ? (!/^(n|no)$/i.test((await session.question("Enable Git worktree isolation for parallel agent sessions? [Y/n]: ")).trim()) ? "auto" : "off")
+            : undefined);
         return {
             ...args,
             scope,
             harness,
             profiles,
             ...(completionGate ? { completionGate: true } : {}),
-            ...(reviewTargets.length === 0 ? {} : { reviewTargets })
+            ...(reviewTargets.length === 0 ? {} : { reviewTargets }),
+            ...(worktree !== undefined ? { worktree } : {})
         };
     }
     finally {

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

@@ -131,7 +131,7 @@ export function buildOpencodePlugin(capabilities, runtimePath) {
         lines.push("  // opencode initializes plugins once per app, not once per session.", "  await runManagedHook($, \"SessionStart\", {", "    event: \"SessionStart\",", "    projectRoot", "  });");
     }
     if (events.includes("PreToolUse")) {
-        lines.push('  hooks["tool.execute.before"] = async (input, output) => {', '    if (input?.tool !== "bash") return;', "    await runManagedHook($, \"PreToolUse\", {", "      event: \"PreToolUse\",", "      projectRoot,", "      input,", "      output", "    });", "  };");
+        lines.push('  const WRITE_TOOLS = ["bash", "edit", "write", "patch", "apply_patch"];', '  hooks["tool.execute.before"] = async (input, output) => {', '    const tool = typeof input?.tool === "string" ? input.tool.toLowerCase() : "";', "    if (!WRITE_TOOLS.includes(tool)) return;", "    await runManagedHook($, \"PreToolUse\", {", "      event: \"PreToolUse\",", "      projectRoot,", "      input,", "      output", "    });", "  };");
     }
     if (events.includes("Stop")) {
         lines.push("  hooks.event = async ({ event }) => {", '    if (event?.type !== "session.idle") return;', "    await runManagedHook($, \"Stop\", { event: \"Stop\", projectRoot });", "  };");

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

@@ -1,8 +1,54 @@
+import { resolve } from "node:path";
 import { normalizeHookEvent } from "../../hooks/normalize.js";
 import { normalizeShellHookEvent } from "../../hooks/shell.js";
+/**
+ * opencode tools that write a file without a shell (lowercase tool names).
+ * `apply_patch` is the GPT-model replacement for `edit`/`write`; older
+ * servers still report `patch`.
+ */
+export const OPENCODE_FILE_TOOLS = new Set([
+    "edit",
+    "write",
+    "patch",
+    "apply_patch"
+]);
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function sessionIdOf(value) {
+    const sessionId = value.sessionID;
+    return typeof sessionId === "string" && sessionId.length > 0
+        ? sessionId
+        : undefined;
+}
+/**
+ * Paths embedded in `apply_patch` marker lines, relative to the project root:
+ * `*** Add File:`, `*** Update File:`, `*** Move to:`, `*** Delete File:`.
+ */
+function patchTextPaths(patchText) {
+    const paths = [];
+    const marker = /^\*\*\*\s+(?:Add File|Update File|Move to|Delete File):\s*(.+?)\s*$/gmu;
+    for (const match of patchText.matchAll(marker)) {
+        const target = match[1]?.trim();
+        if (target !== undefined && target.length > 0 && !target.includes("\0")) {
+            paths.push(target);
+        }
+    }
+    return paths;
+}
+function fileWritePaths(args, projectRoot) {
+    const direct = args.filePath ?? args.file_path ?? args.path;
+    if (typeof direct === "string" && direct.length > 0 && !direct.includes("\0")) {
+        return [resolve(projectRoot, direct)];
+    }
+    if (typeof args.patchText === "string") {
+        const marked = patchTextPaths(args.patchText);
+        if (marked.length > 0) {
+            return marked.map((target) => resolve(projectRoot, target));
+        }
+    }
+    return null;
+}
 /**
  * The managed plugin forwards opencode's own hook payload untouched under
  * `input`, so every field this adapter reads is documented plugin input rather
@@ -21,7 +67,27 @@ export function normalizeOpencodeHookInput(input) {
     }
     if (input.event === "PreToolUse" &&
         isRecord(input.input) &&
-        input.input.tool === "bash" &&
+        typeof input.input.tool === "string" &&
+        OPENCODE_FILE_TOOLS.has(input.input.tool.toLowerCase()) &&
+        isRecord(input.output) &&
+        isRecord(input.output.args) &&
+        typeof projectRoot === "string" &&
+        projectRoot.length > 0) {
+        const paths = fileWritePaths(input.output.args, projectRoot);
+        if (paths !== null) {
+            const sessionId = sessionIdOf(input.input);
+            return {
+                event: "file-write",
+                projectRoot,
+                paths,
+                ...(sessionId === undefined ? {} : { sessionId })
+            };
+        }
+    }
+    if (input.event === "PreToolUse" &&
+        isRecord(input.input) &&
+        typeof input.input.tool === "string" &&
+        input.input.tool.toLowerCase() === "bash" &&
         isRecord(input.output) &&
         isRecord(input.output.args) &&
         typeof input.output.args.command === "string" &&

package/dist/runtime/src/install/parallel-setup.js

@@ -0,0 +1,63 @@
+import { lstat } from "node:fs/promises";
+import { join } from "node:path";
+const LOCKFILES = [
+    { path: "bun.lock", packageManager: "bun" },
+    { path: "bun.lockb", packageManager: "bun" },
+    { path: "npm-shrinkwrap.json", packageManager: "npm" },
+    { path: "package-lock.json", packageManager: "npm" },
+    { path: "pnpm-lock.yaml", packageManager: "pnpm" },
+    { path: "yarn.lock", packageManager: "yarn" }
+];
+const SETUP_COMMANDS = {
+    npm: ["ci"],
+    pnpm: ["install", "--frozen-lockfile"],
+    yarn: ["install", "--immutable"],
+    bun: ["install", "--frozen-lockfile"]
+};
+function hasErrorCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+async function regularFileExists(filePath) {
+    try {
+        const status = await lstat(filePath);
+        return status.isFile() && !status.isSymbolicLink();
+    }
+    catch (error) {
+        if (hasErrorCode(error, "ENOENT")) {
+            return false;
+        }
+        throw error;
+    }
+}
+/**
+ * Detects project lockfiles and proposes safe, deterministic dependency installation
+ * commands for freshly cloned worktrees. Returns an empty array if detection is
+ * ambiguous or unsupported.
+ */
+export async function detectWorktreeSetup(root) {
+    const detected = await Promise.all(LOCKFILES.map(async (def) => (await regularFileExists(join(root, def.path))) ? def.packageManager : null));
+    const managers = [...new Set(detected.filter((m) => m !== null))];
+    if (managers.length !== 1) {
+        return [];
+    }
+    const manager = managers[0];
+    const args = SETUP_COMMANDS[manager];
+    return [{ command: manager, args: [...args] }];
+}
+/**
+ * Returns a warning message if local environment files (.env) are detected
+ * without a .worktreeinclude file to carry them into new worktrees.
+ */
+export async function checkWorktreeEnvWarning(root) {
+    const hasWorktreeInclude = await regularFileExists(join(root, ".worktreeinclude"));
+    if (hasWorktreeInclude) {
+        return undefined;
+    }
+    const envCandidates = [".env", ".env.local"];
+    for (const candidate of envCandidates) {
+        if (await regularFileExists(join(root, candidate))) {
+            return "Local environment files (.env) detected without .worktreeinclude; consider creating .worktreeinclude to copy them to new worktrees.";
+        }
+    }
+    return undefined;
+}

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

@@ -78,7 +78,7 @@ async function detectVerificationCommands(root) {
         blockers: discovery.decisions.map((decision) => `${decision.adapter}: ${decision.message}`)
     };
 }
-function buildConfig(profiles, existing, reviewTargets = [], detectedCommands = [], completionGateEnabled = false) {
+function buildConfig(profiles, existing, reviewTargets = [], detectedCommands = [], completionGateEnabled = false, worktree) {
     // Absent reviewRoles means external review is disabled; an empty selection
     // must therefore omit the field rather than write an empty array.
     const reviewRoles = reviewTargets.length > 0
@@ -88,6 +88,9 @@ function buildConfig(profiles, existing, reviewTargets = [], detectedCommands =
         existing.verification.commands.length > 0
         ? existing.verification
         : { commands: [...detectedCommands] };
+    const effectiveWorktree = worktree !== undefined
+        ? (worktree === null ? undefined : structuredClone(worktree))
+        : (existing?.worktree === undefined ? undefined : structuredClone(existing.worktree));
     return {
         schemaVersion: CONFIG_SCHEMA_VERSION,
         profiles: [...profiles],
@@ -103,12 +106,10 @@ function buildConfig(profiles, existing, reviewTargets = [], detectedCommands =
         pathMappings: existing?.pathMappings ?? [],
         securityExceptions: existing?.securityExceptions ?? [],
         ...(reviewRoles === undefined ? {} : { reviewRoles: [...reviewRoles] }),
-        ...(existing?.worktree === undefined
-            ? {}
-            : { worktree: structuredClone(existing.worktree) })
+        ...(effectiveWorktree === undefined ? {} : { worktree: effectiveWorktree })
     };
 }
-async function planConfig(root, profiles, existingManifest, suppliedConfig, reviewTargets = [], completionGateEnabled = false) {
+async function planConfig(root, profiles, existingManifest, suppliedConfig, reviewTargets = [], completionGateEnabled = false, worktree) {
     const current = await readCurrentFile(root, CONFIG_PATH);
     const owned = findOwnedArtifact(existingManifest, CONFIG_PATH);
     if (current !== null && owned === undefined) {
@@ -144,7 +145,7 @@ async function planConfig(root, profiles, existingManifest, suppliedConfig, revi
         existingConfig.verification.commands.length === 0
         ? await detectVerificationCommands(root)
         : { commands: [], blockers: [] };
-    const config = buildConfig(profiles, existingConfig, reviewTargets, detected.commands, completionGateEnabled);
+    const config = buildConfig(profiles, existingConfig, reviewTargets, detected.commands, completionGateEnabled, worktree);
     const content = `${JSON.stringify(config, null, 2)}\n`;
     return {
         operation: {
@@ -493,7 +494,7 @@ export async function createInstallPlan(options) {
         : [];
     const operations = [];
     const artifacts = [];
-    const config = await planConfig(options.root, resolved.profiles, existing?.manifest ?? null, options.existingConfig, options.reviewTargets ?? [], completionGateEnabled);
+    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);
     for (const artifact of contribution.artifacts) {

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

@@ -123,7 +123,10 @@ export async function createUpdatePlan(options) {
         existingConfig: {
             value: configPreview.migrated,
             sourceHash: configPreview.sourceHash
-        }
+        },
+        ...(options.worktree === undefined
+            ? {}
+            : { worktree: options.worktree })
     });
     return {
         targetVersion,

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

@@ -56,7 +56,7 @@ ensureWorktree) {
                         action: "block",
                         status: "FAIL",
                         code: "WORKTREE_CREATED",
-                        remedy: `worktree.mode is auto, so this session now has its own worktree at ${worktree}. Enter it (Claude Code: EnterWorktree with path ${worktree}) and redo this edit there, at ${join(worktree, relative(mainRoot, target))}.`
+                        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))}.`
                     };
                 }
                 catch (error) {
@@ -68,7 +68,7 @@ ensureWorktree) {
                 action: "block",
                 status: "FAIL",
                 code: "WORKTREE_REQUIRED",
-                remedy: `worktree.mode is auto, so the main checkout is shared and not edited directly.${failure} Run \`agent-ops worktree add <name> --session ${session}\` in ${mainRoot}, enter the printed path (Claude Code: EnterWorktree with that path), and edit there.`
+                remedy: `worktree.mode is auto, so the main checkout is shared and not edited directly.${failure} Run \`agent-ops worktree add <name> --session ${session}\` in ${mainRoot}, enter the printed path (Claude Code: EnterWorktree with that path; otherwise use it as every command's working directory), and edit there.`
             };
         }
     }

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

@@ -34,6 +34,30 @@ export async function probeReviewTarget(target, options) {
         ? await mkdtemp(join(tmpdir(), "agent-ops-review-probe-"))
         : options.cwd;
     try {
+        // agy's sandbox only answers inside a project-shaped directory: an empty
+        // temp dir hangs or denies file access, which this probe then misreads as
+        // unauthenticated. Cloning first matches the review attempt, which already
+        // runs inside a disposable clone; a failed clone falls back to the plain
+        // temp dir, which is exactly today's behavior.
+        let invocationCwd = directory;
+        if (deep && target === "agy") {
+            const clone = join(directory, "repository");
+            const cloned = await runVerificationCommand({
+                id: "review-probe-clone",
+                command: "git",
+                args: ["clone", "--no-hardlinks", "--quiet", "--", options.cwd, clone],
+                cwd: directory,
+                required: true,
+                evidence: { kind: "exit-code" },
+                timeoutMs: Math.min(probeTimeoutMs(options.timeoutMs), 30_000)
+            }, {
+                cwd: directory,
+                ...(options.runner === undefined ? {} : { runner: options.runner })
+            });
+            if (cloned.status === "PASS") {
+                invocationCwd = clone;
+            }
+        }
         const invocation = buildProbeInvocation({
             target,
             prompt: PROBE_PROMPT,
@@ -48,12 +72,12 @@ export async function probeReviewTarget(target, options) {
             id: `review-probe-${target}`,
             command: invocation.command,
             args: deep ? [...invocation.args] : ["--version"],
-            cwd: directory,
+            cwd: invocationCwd,
             required: true,
             evidence: { kind: "exit-code" },
             timeoutMs: probeTimeoutMs(options.timeoutMs)
         }, {
-            cwd: directory,
+            cwd: invocationCwd,
             ...(options.runner === undefined ? {} : { runner: options.runner }),
             ...(deep
                 ? {

package/docs/en/guides/configuration.md

@@ -149,17 +149,18 @@ evidence. Give each editing conversation its own worktree instead:
 
 - `mode: "auto"` routes every editing conversation through
   `agent-ops worktree add <name> --session <id>`, run from the main checkout.
-  On Claude Code a direct Edit or Write of the main checkout outside
+  On Claude Code and opencode a direct Edit or Write of the main checkout outside
   `.worktrees/` is denied (run `agent-ops update` once so the PreToolUse hook
   matches the file tools). Absent or `"off"` keeps today's single checkout.
 - `agent-ops task create` run from the main checkout with a known session
   creates that session's worktree first (or reuses it) and records the task
   there, so the work starts in the worktree. Its output names the path to
   enter and the `--base` to verify against.
-- As a fallback on Claude Code, the first denied edit creates that worktree:
+- As a fallback on Claude Code and opencode, the first denied edit creates that worktree:
   `.worktrees/session-<first eight characters of the session id>`, setup
   included, bound to the session. The denial names the path to enter with
-  EnterWorktree; a later denial for the same session reuses it. If creation
+  EnterWorktree on Claude Code, or to use as every command's working directory
+  otherwise; a later denial for the same session reuses it. If creation
   fails, the denial says why and falls back to the manual `worktree add`.
   Run `agent-ops update` once so the PreToolUse hook gets the 600-second
   timeout setup needs.

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

@@ -132,16 +132,17 @@ fingerprint，因此兩個對話修改同一個 checkout 會互相作廢對方
 ```
 
 - `mode: "auto"` 讓每個修改中的對話都先在主 checkout 執行
-  `agent-ops worktree add <name> --session <id>`。Claude Code 直接以 Edit 或
+  `agent-ops worktree add <name> --session <id>`。Claude Code 與 opencode 直接以 Edit 或
   Write 修改主 checkout 中 `.worktrees/` 以外的檔案會被拒絕（需先執行一次
   `agent-ops update`，讓 PreToolUse hook 比對檔案工具）。未設定或 `"off"` 則維持
   目前的單一 checkout。
 - 在主 checkout、已知 session 的情況下執行 `agent-ops task create`，會先建立（或重用）
   該 session 的 worktree，並把 task 記錄在那裡，讓工作一開始就在 worktree 內。輸出會列出
   要進入的路徑與 verify 用的 `--base`。
-- 作為 Claude Code 上的後備，第一次被拒絕的編輯會自動建立該 worktree：
+- 作為 Claude Code 與 opencode 上的後備，第一次被拒絕的編輯會自動建立該 worktree：
   `.worktrees/session-<session id 前八個字元>`，包含 setup，並綁定該 session。
-  拒絕訊息會列出要以 EnterWorktree 進入的路徑；同一 session 之後被拒絕時會重用它。
+  拒絕訊息會列出要進入的路徑（Claude Code 以 EnterWorktree 進入，其他 harness
+  則作為每條命令的工作目錄）；同一 session 之後被拒絕時會重用它。
   建立失敗時，拒絕訊息會說明原因並退回手動 `worktree add`。需先執行一次
   `agent-ops update`，讓 PreToolUse hook 取得 setup 所需的 600 秒逾時。
 - `add` 從主 checkout 的 HEAD 建立 `.worktrees/<name>` 與 branch

package/package.json

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