@kylecheng3146/agent-ops 0.3.6 → 0.4.0

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

@@ -1,8 +1,9 @@
 import { execFile as execFileCallback } from "node:child_process";
 import { dirname, join, resolve } from "node:path";
-import { lstat, realpath } from "node:fs/promises";
+import { appendFile, lstat, realpath } from "node:fs/promises";
 import { promisify } from "node:util";
 import { applyManagedBlock } from "../fs/managed-block.js";
+import { AgentOpsError } from "../fs/paths.js";
 import { evaluateGuardrail } from "../guardrails/evaluate.js";
 import { appendLocalLog } from "../logging/local-log.js";
 import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
@@ -394,18 +395,29 @@ function parseSessionMarker(source) {
     }
     const session = source.match(/^Session: (\S+)$/mu)?.[1];
     const task = source.match(/^Task: (\S+)$/mu)?.[1];
+    const contested = /^Contested: yes$/mu.test(source);
     return {
         ...(session === undefined ? {} : { sessionId: session }),
-        ...(task === undefined ? {} : { taskId: task })
+        ...(task === undefined ? {} : { taskId: task }),
+        ...(contested ? { contested } : {})
     };
 }
+/**
+ * A different session starting inside this window means two are open in one
+ * checkout.
+ *
+ * ponytail: a session idle for longer than this is not noticed; hosts that
+ * inject their own id (Claude Code, Codex) never depend on the marker at all.
+ */
+const CONTEST_WINDOW_MS = 15 * 60 * 1000;
 /**
  * The bridge the CLI cannot build for itself: a hook is told the session id,
  * a command run inside that session is not. Recording it here lets
  * `agent-ops task attach` default to the session actually running.
  *
- * ponytail: last writer wins. Two concurrent sessions in one checkout already
- * violate the one-writer rule; pass `--session` explicitly if you need that.
+ * The last writer wins, but a different session replacing a recent one marks
+ * the checkout contested, so a command that has to guess its session refuses
+ * instead of acting as the wrong one (`resolveCommandSessionId`).
  */
 export async function writeSessionMarker(options) {
     const path = loopPath(options.root, options.harness, "loop-state.md");
@@ -414,12 +426,22 @@ export async function writeSessionMarker(options) {
         const baseline = source ?? "# Loop state\n";
         const previous = parseSessionMarker(source);
         const taskId = options.taskId ?? previous.taskId;
+        const replaced = previous.sessionId !== undefined &&
+            previous.sessionId !== options.sessionId;
+        const age = replaced
+            ? (options.now?.() ?? Date.now()) -
+                await lstat(path).then((status) => status.mtimeMs, () => 0)
+            : 0;
+        const contested = replaced
+            ? age < CONTEST_WINDOW_MS
+            : previous.contested === true;
         await writePrivateFile(path, applyManagedBlock(baseline, {
             id: LOOP_SESSION_ID,
             version: 1,
             content: [
                 `Session: ${options.sessionId}`,
-                ...(taskId === undefined ? [] : [`Task: ${taskId}`])
+                ...(taskId === undefined ? [] : [`Task: ${taskId}`]),
+                ...(contested ? ["Contested: yes"] : [])
             ].join("\n")
         }), options.root);
     });
@@ -430,6 +452,9 @@ export async function writeSessionMarker(options) {
  * written marker wins, because a checkout may carry both.
  */
 export async function readRecordedSessionId(root) {
+    return (await readRecordedSession(root))?.sessionId;
+}
+async function readRecordedSession(root) {
     const candidates = [];
     for (const harness of ["claude", "codex"]) {
         const path = loopPath(root, harness, "loop-state.md");
@@ -439,13 +464,40 @@ export async function readRecordedSessionId(root) {
                 continue;
             }
             const status = await lstat(path);
-            candidates.push({ sessionId: marker.sessionId, at: status.mtimeMs });
+            candidates.push({
+                sessionId: marker.sessionId,
+                contested: marker.contested === true,
+                at: status.mtimeMs
+            });
         }
         catch {
             continue;
         }
     }
-    return candidates.sort((left, right) => right.at - left.at)[0]?.sessionId;
+    return candidates.sort((left, right) => right.at - left.at)[0];
+}
+/** The id the host injected into this command's environment, if any. */
+export function sessionIdFromEnvironment(env = process.env) {
+    return [env.AGENT_OPS_SESSION_ID, env.CODEX_THREAD_ID]
+        .find((value) => value !== undefined && value !== "");
+}
+/**
+ * Who is running this command: the injected id, else the one a SessionStart
+ * recorded for this checkout. A recorded id another session has since
+ * contested is a guess, and acting as the wrong session is worse than
+ * stopping.
+ */
+export async function resolveCommandSessionId(root, env = process.env) {
+    const injected = sessionIdFromEnvironment(env);
+    if (injected !== undefined) {
+        return injected;
+    }
+    const recorded = await readRecordedSession(root);
+    if (recorded?.contested === true) {
+        throw new AgentOpsError("SESSION_ID_AMBIGUOUS", "Another session started in this checkout recently, so its recorded session id may not be yours. " +
+            "Pass --session <id>, or set AGENT_OPS_SESSION_ID.");
+    }
+    return recorded?.sessionId;
 }
 /**
  * The task attached to this session, never merely the most recent one: a
@@ -650,6 +702,14 @@ export async function runProjectLoop(options) {
                 sessionId,
                 ...(restore.taskId === undefined ? {} : { taskId: restore.taskId })
             }).catch(() => undefined);
+            // Claude Code sources this file before every Bash command, so each of
+            // this session's commands knows who it is. `sessionId` matched
+            // SESSION_ID_PATTERN, which is why it is safe to write unquoted.
+            const envFile = (options.env ?? process.env).CLAUDE_ENV_FILE;
+            if (options.harness === "claude" && envFile !== undefined && envFile !== "") {
+                await appendFile(envFile, `export AGENT_OPS_SESSION_ID=${sessionId}\n`)
+                    .catch(() => undefined);
+            }
         }
         try {
             const [goal, telemetryEntries] = await Promise.all([

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

@@ -234,6 +234,23 @@ export class CompletionGateService {
             ? `Git-visible changes require an attached completed task, current PASS evidence, and a PASS review. Session: ${sessionId}. Create with --session ${sessionId}; one-time permit: agent-ops allow-stop --session ${sessionId}.`
             : undefined);
     }
+    /** Best effort: no baseline only means Stop keeps blocking, as before. */
+    async #backfill(sessionId) {
+        try {
+            if (await this.#store.read(sessionId) !== null)
+                return;
+            const baselineFingerprint = await this.#fingerprint();
+            await this.#store.mutate(sessionId, (current) => current ?? {
+                schemaVersion: 1,
+                sessionId,
+                baselineFingerprint,
+                permitFingerprint: null
+            });
+        }
+        catch {
+            return;
+        }
+    }
     async grantPermit(sessionId) {
         const fingerprint = await this.#fingerprint();
         await this.#store.mutate(sessionId, (state) => {
@@ -320,8 +337,14 @@ export class CompletionGateService {
         if (event.event === "session-start") {
             return await this.initialize(sessionId);
         }
-        if (event.event !== "stop")
+        if (event.event !== "stop") {
+            // A session whose SessionStart never reached this checkout has no
+            // baseline, and the first tool call is the earliest safe moment to take
+            // one. Stop never is: a baseline taken there would swallow the change.
+            if (event.event !== "unsupported")
+                await this.#backfill(sessionId);
             return null;
+        }
         if (event.terminationReason === undefined ||
             (event.terminationReason === "model_stop" && event.fullyIdle === undefined)) {
             return gateResult("block", "UNKNOWN", "COMPLETION_GATE_STOP_INPUT_INVALID", "Restore the Stop termination reason and fullyIdle metadata before stopping.");
@@ -332,7 +355,9 @@ export class CompletionGateService {
         const fingerprint = await this.#fingerprint();
         const state = await this.#store.read(sessionId);
         if (state === null) {
-            return gateResult("block", "UNKNOWN", "COMPLETION_GATE_NOT_INITIALIZED", "The session baseline is unavailable; continue once so PreInvocation can initialize it.");
+            return gateResult("block", "UNKNOWN", "COMPLETION_GATE_NOT_INITIALIZED", this.#options.harness === "agy"
+                ? "The session baseline is unavailable; continue once so PreInvocation can initialize it."
+                : "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) {

package/dist/runtime/src/hooks/dispatch.js

@@ -57,6 +57,11 @@ export async function dispatchHookEvent(event, options) {
             ? continueWith("PASS", "HOOK_NOOP")
             : await options.worktreeGuard(event);
     }
+    if (event.event === "enter-worktree") {
+        return options.worktreeEnter === undefined
+            ? continueWith("PASS", "HOOK_NOOP")
+            : await options.worktreeEnter(event);
+    }
     if (event.event === "session-start" &&
         options.capabilities.includes("lifecycle-summary") &&
         options.advisory !== undefined) {

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

@@ -4,6 +4,7 @@ import { formatInstallManifest, parseInstallManifest } from "../fs/manifest.js";
 import { AgentOpsError, resolveContainedPath } from "../fs/paths.js";
 import { FileTransaction } from "../fs/transaction.js";
 import { validateConfig } from "../schema/validate.js";
+import { applyPreauth } from "./preauth.js";
 const CONFIG_PATH = ".agent-ops/config.json";
 const MANIFEST_PATH = ".agent-ops/manifest.json";
 async function readInstalledFile(root, path) {
@@ -67,4 +68,5 @@ export async function applyInstallPlan(root, plan) {
     assertManifestOperation(plan);
     const transaction = new FileTransaction(root);
     await transaction.apply({ operations: plan.operations }, async () => await validateAppliedPlan(root, plan));
+    await applyPreauth(plan.preauthorization ?? []);
 }

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

@@ -460,7 +460,9 @@ async function checkReviewTargets(config, probe, checkAuth, selectedTargets = []
     const failures = [];
     const degraded = [];
     for (const target of targets) {
-        const result = await probe(target, checkAuth);
+        const answer = await probe(target, checkAuth);
+        const result = typeof answer === "string" ? answer : answer.result;
+        const diagnostic = typeof answer === "string" ? undefined : answer.diagnostic;
         if (result === "missing-executable") {
             failures.push(check("review-targets", "FAIL", `${target} not found.`, undefined, `Install ${target}, or remove "${target}" from reviewRoles[].targets.`));
             continue;
@@ -475,10 +477,19 @@ async function checkReviewTargets(config, probe, checkAuth, selectedTargets = []
             failures.push(check("review-targets", "FAIL", `${target} did not answer in time.`, undefined, "Re-run: agent-ops doctor --check-auth"));
             continue;
         }
+        if (result === "network-unreachable") {
+            failures.push(check("review-targets", "FAIL", `${target} could not reach the network, so its login state is unknown.`, undefined, "Run agent-ops outside the sandbox, or grant it escalated execution, then re-run: agent-ops doctor --check-auth"));
+            continue;
+        }
         if (result === "capability-unavailable") {
             failures.push(check("review-targets", "FAIL", `${target} could not complete its read-only capability probe.`, undefined, "Run agent-ops review on a host with network and loopback permission, then retry."));
             continue;
         }
+        if (result === "probe-failed") {
+            failures.push(check("review-targets", "FAIL", `${target} failed its probe${diagnostic === undefined ? "" : `: ${diagnostic}`}. ` +
+                "This is not evidence of a missing login.", undefined, "Fix what the message reports, or run agent-ops review --json for the full preflight record, then re-run: agent-ops doctor --check-auth"));
+            continue;
+        }
         if (checkAuth && result !== "ok") {
             failures.push(check("review-targets", "FAIL", `${target} is installed but not authenticated, or it rejected the call.`, undefined, `Run: ${target} login`));
         }

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

@@ -48,7 +48,8 @@ function jsonHookRegistered(control, source, capabilities) {
         control.isManagedHandler === undefined) {
         return false;
     }
-    const events = Object.keys(control.buildHooks(capabilities, "probe").hooks);
+    const expected = control.buildHooks(capabilities, "probe").hooks;
+    const events = Object.keys(expected);
     if (events.length === 0) {
         return true;
     }
@@ -57,12 +58,22 @@ function jsonHookRegistered(control, source, capabilities) {
         return false;
     }
     const hooks = parsed.hooks;
+    const isManaged = control.isManagedHandler;
+    const ownsHandler = (group, matcher) => isRecord(group) &&
+        (matcher === undefined || group.matcher === matcher) &&
+        Array.isArray(group.hooks) &&
+        group.hooks.some(isManaged);
     return events.every((event) => {
         const groups = hooks[event];
+        // A matcher is part of the registration: one written before a tool was
+        // added to it still holds a managed handler, which never fires for that tool.
+        const matchers = [expected[event]]
+            .flat()
+            .filter(isRecord)
+            .flatMap((group) => typeof group.matcher === "string" ? [group.matcher] : []);
         return (Array.isArray(groups) &&
-            groups.some((group) => isRecord(group) &&
-                Array.isArray(group.hooks) &&
-                group.hooks.some(control.isManagedHandler)));
+            groups.some((group) => ownsHandler(group)) &&
+            matchers.every((matcher) => groups.some((group) => ownsHandler(group, matcher))));
     });
 }
 function runtimeFailureResult(capability, registrations, remedy) {
@@ -308,7 +319,7 @@ export function managedRules(descriptor, context) {
         ""
     ];
     if (context.capabilities.includes("rules")) {
-        lines.push("For every change:", "", "1. Define two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope and preserve unrelated changes.", "3. Apply the smallest safe change.", "4. Run evidence-producing verification for every criterion.", "5. Obtain complete independent review before claiming completion, via", "   `agent-ops review --task <task-id> --yes` (or the CLI's equivalent invocation).", "   Never call a", "   review-target CLI (agy, codex, claude) directly — direct calls skip", "   the enforced read-only sandbox flags and can hang or fail on command", "   permission prompts.", "   Start this command through the trusted outer host runner as its first", "   and only invocation. On Codex, the outer tool request must use", "   `sandbox_permissions: \"require_escalated\"` so network and loopback", "   are available; in that same request, unset", "   `CODEX_SANDBOX_NETWORK_DISABLED` and set `AGENT_OPS_HOST` when three", "   targets are configured. The Codex shell form is", "   `env -u CODEX_SANDBOX_NETWORK_DISABLED AGENT_OPS_HOST=<current-host> agent-ops review --task <task-id> --yes`.", "   Do not run it once in the restricted sandbox and retry; changing the", "   variable inside that sandbox is not elevation.", "   Review runs exactly two fresh sessions: with three configured targets,", "   set `AGENT_OPS_HOST` to the current CLI id so it is excluded; with two", "   targets both run in configured order; with one target it runs twice.", "   The first session is necessary; a PASS then requires an adversarial", "   re-check carrying the first report. A first FAIL or NOT_RUN stops.", "", "Treat `.agent-ops/config.json` as verifier authority. Discovery output is", "only a proposal until a user confirms it. Repository commands require an", "exact matching trust record. Confirmed project init/update grants it", "automatically when verification commands are configured.", "");
+        lines.push("For every change:", "", "1. Define two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope and preserve unrelated changes.", "3. Apply the smallest safe change.", "4. Run evidence-producing verification for every criterion.", "5. Obtain complete independent review before claiming completion, via", "   `agent-ops review --task <task-id> --yes` (or the CLI's equivalent invocation).", "   Never call a", "   review-target CLI (agy, codex, claude) directly — direct calls skip", "   the enforced read-only sandbox flags and can hang or fail on command", "   permission prompts.", "   Start this command through the trusted outer host runner as its first", "   and only invocation. On Codex, the outer tool request must use", "   `sandbox_permissions: \"require_escalated\"` so network and loopback", "   are available; in that same request, unset", "   `CODEX_SANDBOX_NETWORK_DISABLED` and set `AGENT_OPS_HOST` when three", "   targets are configured. The Codex shell form is", "   `env -u CODEX_SANDBOX_NETWORK_DISABLED AGENT_OPS_HOST=<current-host> agent-ops review --task <task-id> --yes`.", "   Keep it a plain command line: to keep the output add `--output <file>`", "   (the JSON envelope is written there and one line is printed) instead of", "   a shell redirect, which the host can only allow by matching the whole", "   command string, task id included.", "   Do not run it once in the restricted sandbox and retry; changing the", "   variable inside that sandbox is not elevation.", "   Review runs exactly two fresh sessions: with three configured targets,", "   set `AGENT_OPS_HOST` to the current CLI id so it is excluded; with two", "   targets both run in configured order; with one target it runs twice.", "   The first session is necessary; a PASS then requires an adversarial", "   re-check carrying the first report. A first FAIL or NOT_RUN stops.", "", "Treat `.agent-ops/config.json` as verifier authority. Discovery output is", "only a proposal until a user confirms it. Repository commands require an", "exact matching trust record. Confirmed project init/update grants it", "automatically when verification commands are configured.", "");
     }
     if (context.capabilities.includes("task")) {
         lines.push("Split a change that exceeds five acceptance criteria into subtasks:", "`agent-ops task create --parent <task-id>` records one, and", "`agent-ops task status --parent <task-id>` lists them. Each subtask", "carries its own criteria, verification, and independent review;", "completing one never completes its parent.", "", "Delegate a subtask whose scope spans unknown files, broad scans, or an", "independent workstream instead of doing it inline. Name the bounded", "scope, the artifact to return, and the acceptance criteria it serves.", subagentInstruction(descriptor), "Read every returned artifact back yourself: integration, verification,", "and review stay with the coordinator.", "", "One writer at a time. `agent-ops verify` and `agent-ops review`", "fingerprint the working tree and report UNKNOWN when anything else", "writes it during the run, so delegate edits to one subagent at a time,", "or give each writer its own Git worktree and merge before verifying.", "Read-only delegation has no such limit and may run in parallel.", "", "Parallel conversations in one repository each need their own worktree.", "When `.agent-ops/config.json` sets `worktree.mode` to `auto`, run", "`agent-ops task create` from the main checkout before your first edit:", "it creates this session's worktree and puts the task there (`agent-ops", "worktree add <name> --session <session-id>` does the same without a", "task). Work only inside the printed path", "(Claude Code: EnterWorktree with that path; otherwise use it as every", "command's working directory). Commit, then run verify and review for", "each task with the printed `--base`; do not run `task complete` in the", "worktree. Leave it (Claude Code: ExitWorktree with action keep) and run", "`agent-ops worktree finish <name>` from the main checkout: it completes", "every task in the worktree, subtasks first, then merges. A finish that", "reports an incomplete task names it; verify or review that task again", "in the worktree and finish again. A finish that reports a conflict is", "resolved once, as a new task whose criteria cover both intents; if its", "verification or review fails, reset as instructed and report.", "");

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

@@ -11,6 +11,7 @@ import { assertExpectedManagedBlock, assertSupportedManifestOwnership } from "./
 import { codexHooksExplicitlyDisabled, loopLauncherArtifactId, loopSeeds, planLoopContribution, selectedLoopHarnesses } from "./codex-loop.js";
 import { isOpencodeManagedPlugin } from "../adapters/opencode/config.js";
 import { planHookRegistration, planHookRemoval } from "./hooks.js";
+import { planPreauth } from "./preauth.js";
 import { resolveCapabilities, resolveProfiles } from "./profiles.js";
 const CONFIG_PATH = ".agent-ops/config.json";
 const MANIFEST_PATH = ".agent-ops/manifest.json";
@@ -598,6 +599,13 @@ export async function createInstallPlan(options) {
         content: formatInstallManifest(manifest),
         expectedHash: existing?.hash ?? null
     });
+    const preauthorization = await planPreauth({
+        root: options.root,
+        scope: options.scope,
+        harness: options.harness,
+        desired: config.config.worktree?.mode === "auto",
+        ...(options.codexHome === undefined ? {} : { codexHome: options.codexHome })
+    });
     return {
         scope: options.scope,
         harness: options.harness,
@@ -606,6 +614,7 @@ export async function createInstallPlan(options) {
         config: config.config,
         manifest,
         operations,
+        ...(preauthorization.length === 0 ? {} : { preauthorization }),
         detectedVerification: config.detectedVerification,
         verificationBlockers: config.verificationBlockers
     };

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

@@ -0,0 +1,265 @@
+import { lstat, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { sha256 } from "../fs/hash.js";
+import { AgentOpsError, resolveContainedPath } from "../fs/paths.js";
+import { FileTransaction } from "../fs/transaction.js";
+/**
+ * What a session may do without asking, decided once, when the user confirms
+ * init or update: the commands a worktree session runs itself. `trust`,
+ * `allow-stop`, `init`, `update` and `uninstall` stay out, so the approvals
+ * that are the user's alone remain the user's.
+ */
+export const CLAUDE_LOCAL_SETTINGS_PATH = ".claude/settings.local.json";
+export const CLAUDE_PREAUTH_ALLOW = [
+    "Bash(agent-ops task *)",
+    "Bash(agent-ops verify *)",
+    "Bash(agent-ops review *)",
+    "Bash(agent-ops worktree *)",
+    "Bash(agent-ops doctor *)"
+];
+/** review talks to the reviewer's API, which the sandbox withholds. */
+export const CLAUDE_PREAUTH_UNSANDBOXED = [
+    "agent-ops review",
+    "agent-ops review *"
+];
+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.";
+const HOSTS = ["AGENT_OPS_HOST=codex", "AGENT_OPS_HOST=claude", "AGENT_OPS_HOST=agy"];
+const ENV_PREFIX = ["env", "-u", "CODEX_SANDBOX_NETWORK_DISABLED"];
+function starlarkList(values) {
+    return `[${values.map((value) => typeof value === "string"
+        ? JSON.stringify(value)
+        : `[${value.map((item) => JSON.stringify(item)).join(", ")}]`).join(", ")}]`;
+}
+function rule(options) {
+    const pattern = [
+        ...ENV_PREFIX,
+        ...(options.withHost ? [HOSTS] : []),
+        "agent-ops",
+        ...options.command
+    ];
+    return [
+        "prefix_rule(",
+        `    pattern = ${starlarkList(pattern)},`,
+        '    decision = "allow",',
+        `    justification = ${JSON.stringify(options.justification)},`,
+        `    match = [${JSON.stringify(options.match)}],`,
+        `    not_match = [${JSON.stringify(options.notMatch)}]`,
+        ")"
+    ].join("\n");
+}
+/**
+ * Prefix rules for the exact shapes `.agent-ops/AGENTS.md` tells Codex to run,
+ * with and without AGENT_OPS_HOST, for review and the auth probe. Matching is
+ * by argv prefix, so a shell redirect would defeat it: use `--output`.
+ */
+export const CODEX_RULES_CONTENT = `${[
+    CODEX_RULES_MARKER,
+    ...[true, false].flatMap((withHost) => {
+        const host = withHost ? "AGENT_OPS_HOST=codex " : "";
+        const env = `env -u CODEX_SANDBOX_NETWORK_DISABLED ${host}agent-ops`;
+        return [
+            rule({
+                withHost,
+                command: ["review"],
+                justification: "agent-ops review needs network and loopback outside the sandbox.",
+                match: `${env} review --task task-x --yes --output review.json`,
+                notMatch: `${env} trust grant --scope project --yes`
+            }),
+            rule({
+                withHost,
+                command: ["doctor", "--check-auth"],
+                justification: "agent-ops doctor --check-auth probes review targets, which needs the network outside the sandbox.",
+                match: `${env} doctor --check-auth --json --output doctor.json`,
+                notMatch: `${env} doctor --scope user`
+            })
+        ];
+    })
+].join("\n")}\n`;
+export function codexHomeDirectory(env = process.env) {
+    return env.CODEX_HOME ?? join(env.HOME ?? homedir(), ".codex");
+}
+async function readCurrent(root, path) {
+    const resolved = await resolveContainedPath(root, path);
+    try {
+        if (!(await lstat(resolved)).isFile()) {
+            throw new AgentOpsError("PREAUTH_TARGET_INVALID", `Pre-authorization target must be a regular file: ${path}`);
+        }
+        const content = await readFile(resolved, "utf8");
+        return { content, hash: sha256(content) };
+    }
+    catch (error) {
+        if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+function invalidSettings(reason, cause) {
+    return new AgentOpsError("PREAUTH_SETTINGS_INVALID", `${CLAUDE_LOCAL_SETTINGS_PATH} ${reason}; fix it or remove it, then run agent-ops update.`, cause === undefined ? undefined : { cause });
+}
+function stringList(value, where) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        throw invalidSettings(`has a ${where} that is not a list of strings`);
+    }
+    return [...value];
+}
+/**
+ * The managed entries merged into, or stripped from, the user's own local
+ * settings. Nothing else in the file is touched. `null` content means the file
+ * held nothing but these entries and should go; `undefined` means no change.
+ */
+export function planClaudeLocalSettings(source, desired) {
+    let settings = {};
+    if (source !== null && source.trim() !== "") {
+        let parsed;
+        try {
+            parsed = JSON.parse(source);
+        }
+        catch (error) {
+            throw invalidSettings("is not valid JSON", error);
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            throw invalidSettings("is not a JSON object");
+        }
+        settings = parsed;
+    }
+    const permissions = (settings.permissions ?? {});
+    const sandbox = (settings.sandbox ?? {});
+    if (typeof permissions !== "object" || Array.isArray(permissions) ||
+        typeof sandbox !== "object" || Array.isArray(sandbox)) {
+        throw invalidSettings("has a permissions or sandbox entry that is not an object");
+    }
+    const allow = stringList(permissions.allow, "permissions.allow");
+    const excluded = stringList(sandbox.excludedCommands, "sandbox.excludedCommands");
+    const merge = (current, managed) => desired
+        ? [...current, ...managed.filter((entry) => !current.includes(entry))]
+        : current.filter((entry) => !managed.includes(entry));
+    const nextAllow = merge(allow, CLAUDE_PREAUTH_ALLOW);
+    const nextExcluded = merge(excluded, CLAUDE_PREAUTH_UNSANDBOXED);
+    if (nextAllow.length === allow.length && nextExcluded.length === excluded.length &&
+        nextAllow.every((entry, index) => entry === allow[index]) &&
+        nextExcluded.every((entry, index) => entry === excluded[index])) {
+        return undefined;
+    }
+    const { allow: _allow, ...otherPermissions } = permissions;
+    const { excludedCommands: _excluded, ...otherSandbox } = sandbox;
+    const nextPermissions = {
+        ...otherPermissions,
+        ...(nextAllow.length === 0 ? {} : { allow: nextAllow })
+    };
+    const nextSandbox = {
+        ...otherSandbox,
+        ...(nextExcluded.length === 0 ? {} : { excludedCommands: nextExcluded })
+    };
+    const { permissions: _p, sandbox: _s, ...rest } = settings;
+    const next = {
+        ...rest,
+        ...(Object.keys(nextPermissions).length === 0 ? {} : { permissions: nextPermissions }),
+        ...(Object.keys(nextSandbox).length === 0 ? {} : { sandbox: nextSandbox })
+    };
+    return {
+        content: Object.keys(next).length === 0 ? null : `${JSON.stringify(next, null, 2)}\n`
+    };
+}
+async function claudeChange(root, desired) {
+    const current = await readCurrent(root, CLAUDE_LOCAL_SETTINGS_PATH);
+    const planned = planClaudeLocalSettings(current?.content ?? null, desired);
+    if (planned === undefined) {
+        return undefined;
+    }
+    const summary = desired
+        ? `Adds to ${CLAUDE_LOCAL_SETTINGS_PATH} (existing entries kept): permissions.allow ` +
+            `${JSON.stringify(CLAUDE_PREAUTH_ALLOW)}; sandbox.excludedCommands ${JSON.stringify(CLAUDE_PREAUTH_UNSANDBOXED)}.`
+        : `Removes the agent-ops entries from ${CLAUDE_LOCAL_SETTINGS_PATH}, keeping everything else.`;
+    if (planned.content === null) {
+        return current === null
+            ? undefined
+            : {
+                root,
+                operation: { kind: "remove", path: CLAUDE_LOCAL_SETTINGS_PATH, expectedHash: current.hash },
+                summary,
+                ownedContent: false
+            };
+    }
+    return {
+        root,
+        operation: {
+            kind: "write",
+            path: CLAUDE_LOCAL_SETTINGS_PATH,
+            content: planned.content,
+            expectedHash: current?.hash ?? null
+        },
+        summary,
+        ownedContent: false
+    };
+}
+async function codexChange(codexHome, desired) {
+    const isDirectory = await lstat(codexHome).then((status) => status.isDirectory(), () => false);
+    if (!isDirectory) {
+        return undefined;
+    }
+    const current = await readCurrent(codexHome, CODEX_RULES_PATH);
+    // A rules file of the same name that agent-ops did not write is not ours to
+    // overwrite or delete.
+    if (current !== null && !current.content.startsWith(CODEX_RULES_MARKER)) {
+        return undefined;
+    }
+    if (!desired) {
+        return current === null
+            ? undefined
+            : {
+                root: codexHome,
+                operation: { kind: "remove", path: CODEX_RULES_PATH, expectedHash: current.hash },
+                summary: `Removes ${join(codexHome, CODEX_RULES_PATH)}, the rules agent-ops wrote.`,
+                ownedContent: true
+            };
+    }
+    return current?.content === CODEX_RULES_CONTENT
+        ? undefined
+        : {
+            root: codexHome,
+            operation: {
+                kind: "write",
+                path: CODEX_RULES_PATH,
+                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.`,
+            ownedContent: true
+        };
+}
+/**
+ * What init, update and uninstall change beyond the manifest: the local Claude
+ * settings entries and the Codex rules file. Project scope only; `desired`
+ * false plans the removal of what agent-ops wrote.
+ */
+export async function planPreauth(options) {
+    if (options.scope !== "project") {
+        return [];
+    }
+    const changes = [];
+    if (options.harness.includes("claude")) {
+        changes.push(await claudeChange(options.root, options.desired));
+    }
+    // Codex's home is outside the project, so it is only touched when the caller
+    // names it (the CLI does): planning alone must never reach into a real home.
+    if (options.harness.includes("codex") && options.codexHome !== undefined) {
+        changes.push(await codexChange(options.codexHome, options.desired));
+    }
+    return changes.filter((change) => change !== undefined);
+}
+export async function applyPreauth(changes) {
+    for (const change of changes) {
+        try {
+            await new FileTransaction(change.root).apply({ operations: [change.operation] });
+        }
+        catch (error) {
+            throw new AgentOpsError("PREAUTH_APPLY_FAILED", `The rest was applied, but ${join(change.root, change.operation.path)} was not written; fix that file and run agent-ops update.`, { cause: error });
+        }
+    }
+}

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

@@ -118,3 +118,35 @@ export function repositoryTrustStatus(trust) {
             ? "FAIL"
             : "UNKNOWN";
 }
+/**
+ * Trust is bound to the config hash, so a hand edit of the config is what
+ * usually costs it. The fix is always the user's: `update` lists the commands
+ * it will trust and asks once, which is why nothing here tells an agent to
+ * grant it.
+ */
+const TRUST_REMEDY = "The user grants it, once: run `agent-ops update`, which lists the commands it will trust and asks (or `agent-ops trust grant`).";
+export function repositoryTrustProbe(trust, verificationConfigured) {
+    const status = repositoryTrustStatus(trust);
+    if (trust === "STALE") {
+        return {
+            status,
+            message: "Repository trust binding is stale: the config hash changed since trust was granted, as a hand edit of .agent-ops/config.json does.",
+            code: "TRUST_REQUIRED",
+            remediation: TRUST_REMEDY
+        };
+    }
+    if (trust === "UNTRUSTED") {
+        return {
+            status,
+            message: verificationConfigured
+                ? "Repository is not trusted; Stop verification will not run."
+                : "Repository is not trusted.",
+            ...(verificationConfigured
+                ? { code: "TRUST_REQUIRED", remediation: TRUST_REMEDY }
+                : {
+                    remediation: "No action needed; trust is only required once verification.commands is set."
+                })
+        };
+    }
+    return { status };
+}