@kylecheng3146/agent-ops 0.2.8 → 0.3.0

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

@@ -9,13 +9,15 @@ export const COMMAND_NAMES = [
     "task",
     "verify",
     "review",
-    "allow-stop"
+    "allow-stop",
+    "worktree"
 ];
 const COMMAND_SET = new Set(COMMAND_NAMES);
 const SCOPES = new Set(["project", "user"]);
 const PROFILES = new Set(["advisory", "core", "guardrails", "loop"]);
 // opencode is absent: it has no read-only flag, so it cannot review.
 const REVIEW_TARGETS = new Set(["agy", "claude", "codex"]);
+export const WORKTREE_ACTIONS = ["add", "finish", "list", "resume", "remove"];
 export class CliArgumentError extends Error {
     code;
     option;
@@ -82,6 +84,8 @@ export function parseArgs(argv) {
     let rerun = false;
     let helpSeen = false;
     let versionSeen = false;
+    let worktreeName;
+    let force = false;
     for (let index = 0; index < argv.length; index += 1) {
         const token = argv[index];
         if (token === undefined) {
@@ -243,6 +247,12 @@ export function parseArgs(argv) {
                 }
                 yes = true;
                 break;
+            case "--force":
+                if (force) {
+                    duplicate(token);
+                }
+                force = true;
+                break;
             case "--rerun":
                 if (rerun) {
                     duplicate(token);
@@ -292,6 +302,16 @@ export function parseArgs(argv) {
                     action = token;
                     break;
                 }
+                if (command === "worktree" &&
+                    action === undefined &&
+                    WORKTREE_ACTIONS.includes(token)) {
+                    action = token;
+                    break;
+                }
+                if (command === "worktree" && action !== undefined && action !== "list" && worktreeName === undefined) {
+                    worktreeName = token;
+                    break;
+                }
                 if (command !== undefined) {
                     throw new CliArgumentError("CLI_UNEXPECTED_ARGUMENT", `Unexpected argument: ${token}`);
                 }
@@ -346,7 +366,8 @@ export function parseArgs(argv) {
             checkAuthTargets.length > 0 ||
             dryRun ||
             yes ||
-            rerun) {
+            rerun ||
+            force) {
             throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Only --json may be combined with global help or version.");
         }
         command = helpSeen ? "help" : "version";
@@ -357,6 +378,12 @@ export function parseArgs(argv) {
     if (command === "trust" && action === undefined) {
         throw new CliArgumentError("CLI_ACTION_REQUIRED", "The trust command requires one of: status, grant, revoke.");
     }
+    if (command === "worktree" && action === undefined) {
+        throw new CliArgumentError("CLI_ACTION_REQUIRED", `The worktree command requires one of: ${WORKTREE_ACTIONS.join(", ")}.`);
+    }
+    if (command === "worktree" && action !== "list" && worktreeName === undefined) {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", `worktree ${action} requires a worktree name.`);
+    }
     if (command === "task" && action === undefined) {
         throw new CliArgumentError("CLI_ACTION_REQUIRED", "The task command requires one of: create, status, attach, complete, archive, export.");
     }
@@ -369,6 +396,7 @@ export function parseArgs(argv) {
         command !== "verify" &&
         command !== "review" &&
         command !== "allow-stop" &&
+        !(command === "worktree" && sessionId !== undefined && taskId === undefined) &&
         (hasTaskTargetOptions || hasTaskMutationOptions)) {
         throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Task target options may be used only with task or verify.");
     }
@@ -483,9 +511,27 @@ export function parseArgs(argv) {
             yes)) {
         throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "allow-stop requires only --session (and optional --json).");
     }
+    if (command === "worktree" &&
+        (scope !== undefined ||
+            harness !== undefined ||
+            profiles.length > 0 ||
+            hasTaskMutationOptions ||
+            dryRun ||
+            yes ||
+            rerun)) {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "worktree accepts only a name, --session and --json.");
+    }
+    if (force && !(command === "worktree" && action === "remove")) {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--force may be used only with worktree remove.");
+    }
+    if (command === "worktree" && action !== "add" && action !== "resume" && sessionId !== undefined) {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", `worktree ${action} takes the session from the worktree; omit --session.`);
+    }
     return {
         command,
         ...(action === undefined ? {} : { action }),
+        ...(worktreeName === undefined ? {} : { worktreeName }),
+        ...(force ? { force } : {}),
         ...(scope === undefined ? {} : { scope }),
         ...(harness === undefined ? {} : { harness }),
         ...(hookTargets.length === 0 ? {} : { hookTargets }),

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

@@ -3,7 +3,7 @@ import { readFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { execFileSync, spawn } from "node:child_process";
+import { execFile, execFileSync, spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { commonHarnessAdapters, harnessHookPath, HARNESS_IDS } from "../../../runtime/src/install/harness.js";
 import { agyRuntimeStatus, agyVersionSupported, hookRegistrationDrift, repositoryTrustStatus, smokeAvailabilityStatus } from "../../../runtime/src/install/probes.js";
@@ -42,6 +42,8 @@ import { CompletionGateService } from "../../../runtime/src/hooks/completion-gat
 import { formatUpdatePlan, runUpdateCommand } from "./commands/update.js";
 import { errorEnvelope } from "./output.js";
 import { runAgyHeadless } from "./agy-headless.js";
+import { runWorktreeCommand } from "./commands/parallel.js";
+import { listWorktrees, worktreeDoctorResult } from "../../../runtime/src/parallel/manage.js";
 const HOOK_RUNTIME_PATH = fileURLToPath(new URL("./hook-entry.js", import.meta.url));
 async function readOptionalText(path) {
     try {
@@ -121,6 +123,59 @@ async function plannedTrustBinding(root, projectConfig) {
         ? null
         : await repositoryTrustBinding(root, config, CLI_VERSION);
 }
+function worktreeDependencies() {
+    const gateFor = async (root, config) => new CompletionGateService({
+        root,
+        config,
+        gitRunner: gitRunner(root),
+        taskService: new TaskService(new FileTaskStore(join(root, ".agent-ops", "tasks", "state.json"), root)),
+        evidenceStore: new FileEvidenceStore(root, root)
+    });
+    return {
+        git: async (cwd, gitArgs) => await new Promise((resolve) => {
+            execFile("git", [...gitArgs], { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }, (error, stdout, stderr) => resolve({
+                exitCode: error === null ? 0 : typeof error.code === "number" ? error.code : 1,
+                stdout,
+                stderr
+            }));
+        }),
+        loadConfig: async (root) => (await loadEffectiveConfig(root, "project")).config,
+        trust: {
+            status: async (root, config) => await repositoryTrust(root, config, CLI_VERSION),
+            grant: async (root, config) => await trustStore().grant(await repositoryTrustBinding(root, config, CLI_VERSION)),
+            revoke: async (root, config) => {
+                await trustStore().revoke(await repositoryTrustBinding(root, config, CLI_VERSION));
+            }
+        },
+        gate: gateFor,
+        tasks: (root) => new TaskService(new FileTaskStore(join(root, ".agent-ops", "tasks", "state.json"), root)),
+        processRunner: new NodeVerificationProcessRunner(),
+        runSetup: async (cwd, step) => await new Promise((resolve) => {
+            execFile(step.command, [...step.args], {
+                cwd,
+                encoding: "utf8",
+                timeout: step.timeoutMs,
+                maxBuffer: 16 * 1024 * 1024,
+                ...(process.platform === "win32" ? { shell: true } : {})
+            }, (error, stdout, stderr) => resolve({
+                exitCode: error === null
+                    ? 0
+                    : typeof error.code === "number" && error.killed !== true ? error.code : null,
+                output: `${stdout}${stderr}`
+            }));
+        })
+    };
+}
+async function worktreeDoctorProbe(root) {
+    let statuses;
+    try {
+        statuses = await listWorktrees(worktreeDependencies(), root);
+    }
+    catch {
+        return { status: "PASS", message: "No agent-ops worktrees to inspect." };
+    }
+    return worktreeDoctorResult(statuses, Date.now());
+}
 const argv = process.argv.slice(2);
 function runAgy(args, options = {}) {
     return execFileSync("agy", [...args], {
@@ -188,7 +243,8 @@ else {
             "task",
             "verify",
             "review",
-            "allow-stop"
+            "allow-stop",
+            "worktree"
         ].map((command) => [command, async (args) => {
                 const root = args.scope === "user"
                     ? process.env.AGENT_OPS_HOME ?? homedir()
@@ -224,6 +280,13 @@ else {
                         confirm: async (plan, trust, warnings) => await confirmInit(plan, trust, warnings)
                     });
                 }
+                if (args.command === "worktree") {
+                    return await runWorktreeCommand({
+                        args,
+                        cwd: root,
+                        deps: worktreeDependencies()
+                    });
+                }
                 if (args.command === "doctor") {
                     const doctorManifest = await installedManifest(root);
                     const config = (await loadEffectiveConfig(root, args.scope === "user" ? "user" : "project")).config;
@@ -307,7 +370,8 @@ else {
                                     }
                                     : { status };
                             },
-                            reviewTarget: async (target, deep) => await probeReviewTarget(target, { cwd: root, deep })
+                            reviewTarget: async (target, deep) => await probeReviewTarget(target, { cwd: root, deep }),
+                            worktrees: async () => await worktreeDoctorProbe(root)
                         },
                         ...(args.checkAuth === true
                             ? { checkReviewTargetAuth: true }

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

@@ -29,6 +29,8 @@ Commands:
   review     Run an independent review
   allow-stop Grant one fingerprint-bound completion-gate Stop permit (requires --session)
   agy-run    Run headless agy with a process-exit completion recheck
+  worktree <add|finish|list|resume|remove>
+             Give one session its own Git worktree for parallel work
 
 Options:
   --scope <project|user>
@@ -179,6 +181,35 @@ agent cannot self-authorize it.
 Options:
   --session <id>   Required
   --json
+`,
+    worktree: `Usage: agent-ops worktree <add|finish|resume|remove> <name> [options]
+       agent-ops worktree list [--json]
+
+Give one writing session its own Git worktree, so parallel sessions stop
+voiding each other's verification and review. Run it from the main checkout.
+
+  add <name>   Create .worktrees/<name> on branch agent-ops/<name> from HEAD,
+               copy the ignored agent-ops files and .worktreeinclude matches,
+               inherit trust for an identical config, run worktree.setup, and
+               point the session's completion gate at the new worktree.
+  finish <name>
+               Once its task is complete, fast-forward the main checkout's
+               branch to the worktree's (after a clean rebase and
+               re-verification if the branch moved), record the task in
+               git notes, and remove the worktree. One finish runs at a time.
+  list         Every agent-ops worktree: session, commits ahead, uncommitted
+               changes, task status and last activity.
+  resume <name>
+               Hand a worktree whose session ended to --session <id>.
+  remove <name>
+               Delete the worktree and its branch. Uncommitted or unmerged
+               work needs --force, which the completion gate asks the user
+               about.
+
+Options:
+  --session <id>   add, resume: the conversation that will work there (required)
+  --force          remove: discard uncommitted or unmerged work
+  --json
 `
 };
 function wantsJson(argv) {

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

@@ -47,7 +47,10 @@ export async function runHookCommand(options) {
             ...(stopVerification === undefined ? {} : { stopVerification }),
             ...(options.completionGate === undefined
                 ? {}
-                : { completionGate: options.completionGate })
+                : { completionGate: options.completionGate }),
+            ...(options.worktreeGuard === undefined
+                ? {}
+                : { worktreeGuard: options.worktreeGuard })
         });
         return descriptor.runtime.formatOutput(options.event, result);
     }

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

@@ -0,0 +1,87 @@
+import { okEnvelope } from "../output.js";
+import { addWorktree } from "../../../../runtime/src/parallel/service.js";
+import { finishWorktree } from "../../../../runtime/src/parallel/finish.js";
+import { idleWorktrees, listWorktrees, removeWorktree, resumeWorktree } from "../../../../runtime/src/parallel/manage.js";
+function listText(statuses, now) {
+    if (statuses.length === 0)
+        return "No agent-ops worktrees.";
+    const idle = new Set(idleWorktrees(statuses, now).map(({ record }) => record.name));
+    return statuses.map(({ record, dirty, ahead, taskStatus, lastActivity }) => [
+        `${record.name}${idle.has(record.name) ? " (idle)" : ""}`,
+        `  path: ${record.path}`,
+        `  session: ${record.sessionId}`,
+        `  branch: ${record.branch}, ${ahead} commit(s) ahead of ${record.targetBranch}${dirty ? ", uncommitted changes" : ""}`,
+        `  task: ${taskStatus}`,
+        `  last activity: ${lastActivity}`
+    ].join("\n")).join("\n");
+}
+function addText(result) {
+    const { record } = result;
+    return [
+        `Created worktree ${record.name} for session ${record.sessionId}.`,
+        `Path: ${record.path}`,
+        `Branch: ${record.branch} (from ${record.targetBranch} at ${record.base})`,
+        `Copied: ${result.copied.length === 0 ? "nothing" : result.copied.join(", ")}`,
+        `Trust: ${result.trusted ? "inherited" : "not inherited; run agent-ops trust grant inside the worktree"}`,
+        ...(result.setup.length === 0 ? [] : [`Setup: ${result.setup.join("; ")}`]),
+        "",
+        "Work only inside that path from now on:",
+        `- Claude Code: EnterWorktree with path ${record.path}`,
+        `- Codex and agy: run every command with ${record.path} as its working directory`,
+        `Finish with: commit, agent-ops verify/review/task complete with --base ${record.base},`,
+        `then agent-ops worktree finish ${record.name} from ${record.mainRoot}`,
+        "(Claude Code: ExitWorktree with action keep before finishing)."
+    ].join("\n");
+}
+function finishText(result) {
+    const { record } = result;
+    return [
+        `Merged ${record.branch} into ${record.targetBranch} at ${result.mergedHead}${result.rebased ? " after a clean rebase and re-verification" : ""}.`,
+        `Task ${result.taskId} is recorded in git notes (refs/notes/agent-ops).`,
+        `Removed ${record.path}.`,
+        ...result.warnings.map((warning) => `Warning: ${warning}`)
+    ].join("\n");
+}
+export async function runWorktreeCommand(options) {
+    const { args } = options;
+    if (args.action === "list") {
+        const worktrees = await listWorktrees(options.deps, options.cwd);
+        return okEnvelope("WORKTREE_LIST", { worktrees, text: listText(worktrees, Date.now()) });
+    }
+    if (args.action === "resume") {
+        const record = await resumeWorktree(options.deps, {
+            cwd: options.cwd,
+            name: args.worktreeName,
+            sessionId: args.sessionId ?? process.env.AGENT_OPS_SESSION_ID
+        });
+        return okEnvelope("WORKTREE_RESUMED", {
+            record,
+            text: [
+                `Session ${record.sessionId} now owns worktree ${record.name}.`,
+                `Path: ${record.path}`,
+                `- Claude Code: EnterWorktree with path ${record.path}`,
+                `- Codex and agy: run every command with ${record.path} as its working directory`,
+                "Its next Stop is judged against everything already in the worktree."
+            ].join("\n")
+        });
+    }
+    if (args.action === "remove") {
+        const removed = await removeWorktree(options.deps, {
+            cwd: options.cwd,
+            name: args.worktreeName,
+            force: args.force === true
+        });
+        return okEnvelope("WORKTREE_REMOVED", { ...removed, text: `Removed ${removed.record.path} and ${removed.record.branch}.` });
+    }
+    if (args.action === "finish") {
+        const finished = await finishWorktree(options.deps, { cwd: options.cwd, name: args.worktreeName });
+        return okEnvelope("WORKTREE_FINISHED", { ...finished, text: finishText(finished) });
+    }
+    const sessionId = args.sessionId ?? process.env.AGENT_OPS_SESSION_ID;
+    const result = await addWorktree(options.deps, {
+        cwd: options.cwd,
+        name: args.worktreeName,
+        sessionId
+    });
+    return okEnvelope("WORKTREE_CREATED", { ...result, text: addText(result) });
+}

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

@@ -9,6 +9,7 @@ import { resolveContainedPath } from "../../../runtime/src/fs/paths.js";
 import { redactSecrets } from "../../../runtime/src/security/redact.js";
 import { claudeStopRecursionMarker } from "../../../runtime/src/adapters/claude/input.js";
 import { HARNESS_IDS, harnessDescriptor } from "../../../runtime/src/install/harness.js";
+import { evaluateWorktreeWrite, resolveMainRoot } from "../../../runtime/src/parallel/guard.js";
 import { CompletionGateService } from "../../../runtime/src/hooks/completion-gate.js";
 import { TaskService } from "../../../runtime/src/task/service.js";
 import { FileTaskStore } from "../../../runtime/src/task/store.js";
@@ -208,6 +209,26 @@ function shouldBuildStopVerification(harness, event, config, rawInput) {
     }
     return harnessDescriptor(harness).control.registrations.some(({ capability, support }) => capability === "optional-stop-verify" && support !== "unsupported");
 }
+/**
+ * The gate of one checkout. A session redirected into a worktree is judged by
+ * that worktree's gate, built the same way from the worktree's own config.
+ */
+function completionGateFor(root, config, gitRunner) {
+    return new CompletionGateService({
+        root,
+        config,
+        gitRunner,
+        taskService: new TaskService(new FileTaskStore(join(root, ".agent-ops", "tasks", "state.json"), root)),
+        evidenceStore: new FileEvidenceStore(root, root),
+        forRoot: async (worktree) => {
+            const outcome = await loadProjectHookConfig(worktree);
+            if (outcome.kind !== "loaded" || !outcome.config.features.completionGate.enabled) {
+                throw new Error("The redirected worktree has no enabled completion gate.");
+            }
+            return completionGateFor(worktree, outcome.config, defaultGitRunner(worktree));
+        }
+    });
+}
 /**
  * Runs one hook invocation. Exit code stays zero because native JSON carries
  * decisions; only an explicitly installed agy completion gate fails closed.
@@ -319,13 +340,15 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
         const completionGate = (harnessId === "agy" || harnessId === "claude") &&
             config.features.completionGate.enabled
             ? dependencies.completionGate ?? {
-                handle: async (normalized) => await new CompletionGateService({
-                    root,
-                    config,
-                    gitRunner,
-                    taskService: new TaskService(new FileTaskStore(join(root, ".agent-ops", "tasks", "state.json"), root)),
-                    evidenceStore: new FileEvidenceStore(root, root)
-                }).handle(normalized)
+                handle: async (normalized) => await completionGateFor(root, config, gitRunner).handle(normalized)
+            }
+            : undefined;
+        const worktreeGuard = config.worktree?.mode === "auto"
+            ? async (write) => {
+                const mainRoot = await resolveMainRoot(gitRunner);
+                return mainRoot === null
+                    ? { action: "continue", status: "UNKNOWN", code: "WORKTREE_GUARD_UNAVAILABLE" }
+                    : await evaluateWorktreeWrite(mainRoot, write.paths, write.sessionId);
             }
             : undefined;
         const output = await runHookCommand({
@@ -334,6 +357,7 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
             stdin: rawInput,
             config,
             trusted,
+            ...(worktreeGuard === undefined ? {} : { worktreeGuard }),
             ...(dependencies.advisory === undefined
                 ? {}
                 : { advisory: dependencies.advisory }),

package/dist/runtime/src/adapters/agy/output.js

@@ -12,7 +12,8 @@ export function agyHookOutput(event, result) {
         ? `agent-ops: ${result.code}`
         : `agent-ops: ${result.code}: ${result.remedy}`;
     const value = event === "PreToolUse"
-        ? result.code === "COMPLETION_GATE_PERMIT_CONFIRMATION"
+        ? result.code === "COMPLETION_GATE_PERMIT_CONFIRMATION" ||
+            result.code === "WORKTREE_REMOVE_CONFIRMATION"
             ? { decision: "force_ask", reason }
             : result.action === "block"
                 ? { decision: "deny", reason }

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

@@ -11,6 +11,7 @@ const CLAUDE_LOOP_EVENTS = [
     "SubagentStop"
 ];
 const CLAUDE_HOOK_MARKER = "--managed-by=agent-ops";
+export const CLAUDE_PRE_TOOL_MATCHER = "Bash|Edit|MultiEdit|NotebookEdit|Write";
 const CLAUDE_LOOP_LAUNCHER = "${CLAUDE_PROJECT_DIR}/.claude/hooks/agent-ops-loop.sh";
 const CLAUDE_WINDOWS_LOOP_LAUNCHER = "${CLAUDE_PROJECT_DIR}/.claude/hooks/agent-ops-loop.ps1";
 export function claudeSettingsTarget(scope) {
@@ -46,7 +47,9 @@ function commandHook(event, runtimePath, completionGate = false) {
 }
 function matcherGroup(event, runtimePath, completionGate = false) {
     return {
-        ...(event === "PreToolUse" ? { matcher: "Bash" } : {}),
+        // File tools as well as Bash: in worktree auto mode the guard must see a
+        // direct edit of the shared checkout, which never passes through a shell.
+        ...(event === "PreToolUse" ? { matcher: CLAUDE_PRE_TOOL_MATCHER } : {}),
         hooks: [commandHook(event, runtimePath, completionGate)]
     };
 }

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

@@ -1,5 +1,13 @@
+import { resolve } from "node:path";
 import { normalizeHookEvent } from "../../hooks/normalize.js";
 import { normalizeShellHookEvent } from "../../hooks/shell.js";
+/** Claude's tools that write a file without a shell. */
+export const CLAUDE_FILE_TOOLS = new Set([
+    "Edit",
+    "MultiEdit",
+    "NotebookEdit",
+    "Write"
+]);
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -39,6 +47,22 @@ export function normalizeClaudeHookInput(input) {
             fullyIdle: input.stop_hook_active !== true
         };
     }
+    if (input.hook_event_name === "PreToolUse" &&
+        typeof input.tool_name === "string" &&
+        CLAUDE_FILE_TOOLS.has(input.tool_name) &&
+        isRecord(input.tool_input) &&
+        typeof projectRoot === "string" &&
+        projectRoot.length > 0) {
+        const target = input.tool_input.file_path ?? input.tool_input.notebook_path;
+        if (typeof target === "string" && target.length > 0 && !target.includes("\0")) {
+            return {
+                event: "file-write",
+                projectRoot,
+                paths: [resolve(projectRoot, target)],
+                ...(sessionId === undefined ? {} : { sessionId })
+            };
+        }
+    }
     if (input.hook_event_name === "PreToolUse" &&
         input.tool_name === "Bash" &&
         isRecord(input.tool_input) &&

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

@@ -19,7 +19,8 @@ export function claudeHookOutput(event, result) {
         });
     }
     if (event === "PreToolUse" &&
-        result.code === "COMPLETION_GATE_PERMIT_CONFIRMATION") {
+        (result.code === "COMPLETION_GATE_PERMIT_CONFIRMATION" ||
+            result.code === "WORKTREE_REMOVE_CONFIRMATION")) {
         // Asked, never allowed: a one-time Stop permit is the user's to grant, and
         // an agent that could answer this for itself would hold the key to its own
         // gate.

package/dist/runtime/src/config/merge.js

@@ -110,9 +110,15 @@ export function mergeConfigLayers(inputLayers) {
     const reviewRoles = new Map();
     let schemaVersion;
     let features;
+    let worktree;
     for (const layer of layers) {
         schemaVersion = effective(layer.config.schemaVersion, layer);
         features = effective(layer.config.features, layer);
+        // Whole-block override: a workflow choice, not a guardrail, so a project
+        // may turn a user-level `auto` off.
+        if (layer.config.worktree !== undefined) {
+            worktree = effective(layer.config.worktree, layer);
+        }
         for (const profile of layer.config.profiles) {
             profiles.set(profile, effective(profile, layer));
         }
@@ -158,7 +164,8 @@ export function mergeConfigLayers(inputLayers) {
         verificationCommands: [...commands.values()],
         pathMappings: [...mappings.values()],
         securityExceptions: [...exceptions.values()],
-        reviewRoles: [...reviewRoles.values()]
+        reviewRoles: [...reviewRoles.values()],
+        ...(worktree === undefined ? {} : { worktree })
     };
     const config = {
         schemaVersion: schemaVersion.value,
@@ -175,7 +182,8 @@ export function mergeConfigLayers(inputLayers) {
             ? {}
             : {
                 reviewRoles: provenance.reviewRoles.map(({ value }) => value)
-            })
+            }),
+        ...(worktree === undefined ? {} : { worktree: worktree.value })
     };
     const validation = validateConfig(config);
     if (!validation.ok) {

package/dist/runtime/src/hooks/codex-loop.js

@@ -407,7 +407,7 @@ function parseSessionMarker(source) {
  * ponytail: last writer wins. Two concurrent sessions in one checkout already
  * violate the one-writer rule; pass `--session` explicitly if you need that.
  */
-async function writeSessionMarker(options) {
+export async function writeSessionMarker(options) {
     const path = loopPath(options.root, options.harness, "loop-state.md");
     await withPrivateFileLock(path, options.root, async () => {
         const source = await readPrivateFile(path, options.root);
@@ -491,6 +491,8 @@ async function restoreState(options) {
 function clamp(value, limit) {
     return value.length <= limit ? value : `${value.slice(0, limit - 14)}\n[truncated]`;
 }
+/** Printed only when it is a plain token: it lands verbatim in agent context. */
+const PRINTABLE_SESSION = /^[A-Za-z0-9._:-]{1,128}$/u;
 function sessionContext(options) {
     // Task state is assembled first and clamped on its own budget, so a long
     // goal can no longer crowd out the one thing recovery exists to carry.
@@ -516,8 +518,15 @@ function sessionContext(options) {
         return [];
     })();
     const telemetry = `Telemetry: ${options.telemetryEntries} recent redacted event(s).`;
+    // The id every `--session` flag wants. Hooks hear it; the agent otherwise
+    // never does, and a shared checkout's recorded marker belongs to whichever
+    // session started last.
+    const session = options.sessionId !== undefined && PRINTABLE_SESSION.test(options.sessionId)
+        ? [`Session: ${options.sessionId}`]
+        : [];
     const fixed = [
         "agent-ops project loop is active.",
+        ...session,
         "",
         ...restored,
         telemetry
@@ -648,6 +657,7 @@ export async function runProjectLoop(options) {
                 telemetryCount(root, options.harness)
             ]);
             return sessionOutput(options.harness, sessionContext({
+                ...(sessionId === undefined ? {} : { sessionId }),
                 goal: safeGoalContext(goal),
                 telemetryEntries,
                 mode: restoreMode(options.input),