@kylecheng3146/agent-ops 0.7.3 → 0.8.3

package/dist/packages/cli/src/debug-intake.js

@@ -0,0 +1,245 @@
+import { join } from "node:path";
+import { TaskService } from "../../../runtime/src/task/service.js";
+import { FileTaskStore } from "../../../runtime/src/task/store.js";
+import { calculateConfigHash } from "../../../runtime/src/config/hash.js";
+import { evaluateGuardrail } from "../../../runtime/src/guardrails/evaluate.js";
+import { isDebugIssue } from "../../../runtime/src/task/debug-intake.js";
+import { ensureSessionWorktree, readWorktreeRecord, sessionWorktreeName } from "../../../runtime/src/parallel/service.js";
+import { listWorktrees, resumeWorktree } from "../../../runtime/src/parallel/manage.js";
+import { collectChangeSurface } from "../../../runtime/src/verify/change-surface.js";
+import { calculateSourceFingerprint } from "../../../runtime/src/verify/source-fingerprint.js";
+import { AgentOpsError } from "../../../runtime/src/fs/paths.js";
+import { loadEffectiveConfig } from "./context.js";
+import { gitRunner, worktreeDependencies } from "./parallel-deps.js";
+const foregroundClockSupported = (host) => host !== "opencode";
+function nativeSessionId(input) {
+    const fromInput = [input.session_id, input.sessionId, input.conversationId, input.thread_id, input.threadId]
+        .find((value) => typeof value === "string" && value.length > 0);
+    return fromInput ?? [process.env.AGENT_OPS_SESSION_ID, process.env.CODEX_THREAD_ID]
+        .find((value) => value !== undefined && value.length > 0);
+}
+/** Start only an already attached DEBUG issue; native hooks never create work. */
+export async function startDebugSession(root, sessionId, host) {
+    if (!foregroundClockSupported(host) || sessionId.length === 0)
+        return;
+    const config = (await loadEffectiveConfig(root, "project")).config;
+    const saved = await readWorktreeRecord(join(root, ".worktrees", sessionWorktreeName(sessionId)));
+    const contextRoot = saved?.mainRoot === root && saved.sessionId === sessionId ? saved.path : root;
+    const contextConfig = contextRoot === root ? config : (await loadEffectiveConfig(contextRoot, "project")).config;
+    const tasks = new TaskService(new FileTaskStore(join(contextRoot, ".agent-ops/tasks/state.json"), contextRoot), { completion: { root: contextRoot, gitRunner: gitRunner(contextRoot), loadConfig: async () => contextConfig } });
+    const attached = await tasks.status({ sessionId }).catch(() => null);
+    if (attached?.status === "active" && attached.task.debug !== undefined)
+        await tasks.debugService().foregroundStart(attached.task.id, sessionId);
+}
+export async function routeDebugPrompt(root, input, host = "claude") {
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return null;
+    const fields = input;
+    if (typeof fields.prompt !== "string")
+        return null;
+    const continuation = /^(?:繼續|继续|continue)[。.!！]?$/iu.test(fields.prompt.trim());
+    const debugIssue = isDebugIssue(fields.prompt);
+    const config = (await loadEffectiveConfig(root, "project")).config;
+    if (config.features.debug?.enabled !== true)
+        return null;
+    if (evaluateGuardrail({ kind: "content", content: fields.prompt, scope: root }).action === "block")
+        return null;
+    const session = nativeSessionId(fields);
+    if (session === undefined) {
+        if (!debugIssue && !continuation)
+            return null;
+        return "DEBUG intake unsupported: this hook has no reliable native session identity. Use task create --debug --goal with the original issue in the native conversation.";
+    }
+    const saved = await readWorktreeRecord(join(root, ".worktrees", sessionWorktreeName(session)));
+    const contextRoot = saved?.mainRoot === root && saved.sessionId === session ? saved.path : root;
+    const contextConfig = contextRoot === root ? config : (await loadEffectiveConfig(contextRoot, "project")).config;
+    const original = new TaskService(new FileTaskStore(join(contextRoot, ".agent-ops/tasks/state.json"), contextRoot), { completion: { root: contextRoot, gitRunner: gitRunner(contextRoot), loadConfig: async () => contextConfig } });
+    const attached = await original.status({ sessionId: session }).catch(() => null);
+    if (attached?.status === "active" && attached.task.debug !== undefined) {
+        await original.debugService().syncNativeControl(attached.task.id, session);
+        const control = (await original.debugService().root(attached.task.id)).debug.control;
+        if (control?.paused === true)
+            return `DEBUG original issue ${attached.task.id} is paused by the human. Preserve its task, evidence and remaining budget; stop after saving progress. Only a native human continue event resumes it.`;
+        if (continuation) {
+            let message = `DEBUG continue preserved original issue ${attached.task.id}: native user event did not extend time; other limits remain authoritative.`;
+            try {
+                await original.debugService().extend(attached.task.id, session, "latest");
+                message = `DEBUG original issue ${attached.task.id}: native human time grant applied once; other limits remain authoritative.`;
+            }
+            catch (error) {
+                message = `DEBUG continue preserved original issue ${attached.task.id}: ${error instanceof Error ? error.message : "Native user approval unavailable"}`;
+            }
+            if (foregroundClockSupported(host)) {
+                try {
+                    await original.debugService().foregroundStart(attached.task.id, session);
+                }
+                catch (error) {
+                    message += ` Foreground clock unavailable: ${error instanceof Error ? error.message : "host lifecycle is unsupported"}`;
+                }
+            }
+            else
+                message += " Foreground clock unsupported on this host; preserve the issue and use a host with a trustworthy end-of-turn signal.";
+            if (control?.mode === "diagnose")
+                message += " Diagnosis-only scope remains active; continue discriminating evidence without product repairs until a proven diagnosis or runtime blocker. Only a native human resume repair event restores the full loop.";
+            return message;
+        }
+        if (foregroundClockSupported(host)) {
+            try {
+                await original.debugService().foregroundStart(attached.task.id, session);
+            }
+            catch (error) {
+                return `DEBUG original issue ${attached.task.id}: foreground clock unavailable: ${error instanceof Error ? error.message : "host lifecycle is unsupported"}`;
+            }
+        }
+        if (control?.mode === "diagnose")
+            return `DEBUG original issue ${attached.task.id}: diagnosis only. Continue reproduction and hypothesis evidence until a supported diagnosis or a runtime blocker. Do not repair product behavior. A failure to reproduce is not a stop condition; a human resume repair event restores the full loop.`;
+        if (!debugIssue)
+            return null;
+        return `Continue original DEBUG issue ${attached.task.id}; retain its existing budget, evidence and hypotheses.`;
+    }
+    if (!debugIssue && !continuation)
+        return null;
+    if (continuation) {
+        if (attached?.status !== "active" || attached.task.debug === undefined)
+            return null;
+        try {
+            await original.debugService().extend(attached.task.id, session, "latest");
+            return `DEBUG original issue ${attached.task.id}: native human time grant applied once; other limits remain authoritative.`;
+        }
+        catch (error) {
+            return `DEBUG continue preserved original issue ${attached.task.id}: ${error instanceof Error ? error.message : "Native user approval unavailable"}`;
+        }
+    }
+    if (attached?.status === "active")
+        return attached.task.debug === undefined ? null : `Continue original DEBUG issue ${attached.task.id}; retain its existing budget, evidence and hypotheses.`;
+    // Another session's worktree may already hold this issue; reusing it keeps
+    // its consumed budget and rounds instead of starting a fresh task.
+    const holders = await listWorktrees(worktreeDependencies(), root).catch(() => []);
+    for (const { record: held } of holders) {
+        if (held.sessionId === session)
+            continue;
+        const heldConfig = (await loadEffectiveConfig(held.path, "project").catch(() => null))?.config;
+        if (heldConfig === undefined)
+            continue;
+        const issue = await new TaskService(new FileTaskStore(join(held.path, ".agent-ops/tasks/state.json"), held.path), { completion: { root: held.path, gitRunner: gitRunner(held.path), loadConfig: async () => heldConfig } }).activeDebugRoot(fields.prompt).catch(() => null);
+        if (issue === null)
+            continue;
+        try {
+            await resumeWorktree(worktreeDependencies(), { cwd: root, name: held.name, sessionId: session });
+        }
+        catch (error) {
+            return `DEBUG original issue ${issue.task.id} is still active in ${held.path}; a new task would reset its budget. ${error instanceof Error ? error.message : "Resume needs confirmation."} After the user confirms, run agent-ops worktree resume ${held.name} --session ${session}.`;
+        }
+        return `Continue original DEBUG issue ${issue.task.id} in ${held.path}; its budget, rounds and evidence are preserved.`;
+    }
+    await original.assertDebugBaseline();
+    const record = config.worktree?.mode === "auto" && await readWorktreeRecord(root) === null ?
+        await ensureSessionWorktree(worktreeDependencies(), { cwd: root, sessionId: session }) : null;
+    const path = record?.path ?? root;
+    const effective = (await loadEffectiveConfig(path, "project")).config;
+    const tasks = new TaskService(new FileTaskStore(join(path, ".agent-ops/tasks/state.json"), path), { completion: { root: path, gitRunner: gitRunner(path), loadConfig: async () => effective } });
+    const existing = await tasks.status({ sessionId: session }).catch(() => null);
+    if (existing?.status === "active")
+        return existing.task.debug === undefined ? null : `Continue original DEBUG issue ${existing.task.id}.`;
+    const held = await tasks.activeDebugRoot(fields.prompt);
+    if (held !== null) {
+        await tasks.attach(session, held.task.id);
+        let message = `Continue original DEBUG issue ${held.task.id}; its budget, rounds and evidence are preserved.`;
+        if (foregroundClockSupported(host)) {
+            try {
+                await tasks.debugService().foregroundStart(held.task.id, session);
+            }
+            catch (error) {
+                message += ` Foreground clock unavailable: ${error instanceof Error ? error.message : "host lifecycle is unsupported"}`;
+            }
+        }
+        return message;
+    }
+    const ids = effective.verification.commands.filter(c => c.required).map(c => c.id);
+    const baseline = (await gitRunner(path).run(["rev-parse", "--verify", "HEAD"])).stdout.toString().trim();
+    const criteria = ["issue-regression", "related-checks"].map(id => ({ id, description: id === "issue-regression" ? "Reproduce and fix the original reported issue with relevant regression evidence." : "Pass necessary related checks and two fresh independent reviews.", verifierIds: ids,
+        acceptance: { mode: "review-only", baselineCommit: baseline, bindings: [], reviewOnlyReason: "Provisional investigation intake only. Identify and revise to executable original-issue regression before debug success; this criterion cannot prove reproduction." } }));
+    const created = await tasks.create({ title: fields.prompt.split("\n")[0].slice(0, 160), goal: fields.prompt, intent: "Investigate and fix the original issue through authoritative task debug evidence.", debug: { facts: ["User-reported symptom is unverified."], unknowns: ["Baseline reproduction", "Root cause", "Relevant regression and related checks"] }, criteria, sessionId: session, policyConfigHash: calculateConfigHash(effective) });
+    let clockNote = "";
+    if (foregroundClockSupported(host)) {
+        try {
+            await tasks.debugService().foregroundStart(created.task.id, session);
+        }
+        catch (error) {
+            return `DEBUG issue ${created.task.id} created in ${path}, but its foreground clock is unavailable: ${error instanceof Error ? error.message : "host lifecycle is unsupported"}. Preserve the issue and do not claim timed completion.`;
+        }
+    }
+    else
+        clockNote = " Native foreground timing is unsupported on this host; controlled operations remain evidence-timed and do not claim a complete active-time budget.";
+    return `DEBUG issue ${created.task.id} created in ${path}. Preserve the original goal. Investigate, record falsifiable hypotheses, revise provisional criteria to relevant behavioral regression, repair, verify, obtain two fresh independent reviews, then finish. A clean HEAD baseline is fixed automatically; do not ask permission for it or offer diagnosis-only as a fallback. Failure to reproduce alone is not a stop condition: continue discriminating checks within the budget. Defaults: 60 active minutes / 5 material repair candidates. No user-authored debug plan is required.${clockNote}`;
+}
+export async function interruptDebugSession(root, sessionId, nativeInput) {
+    const saved = await readWorktreeRecord(join(root, ".worktrees", sessionWorktreeName(sessionId)));
+    const path = saved?.mainRoot === root && saved.sessionId === sessionId ? saved.path : root;
+    const tasks = new TaskService(new FileTaskStore(join(path, ".agent-ops/tasks/state.json"), path), { completion: { root: path, gitRunner: gitRunner(path), loadConfig: async () => (await loadEffectiveConfig(path, "project")).config } });
+    const attached = await tasks.status({ sessionId }).catch(error => {
+        if (error instanceof AgentOpsError && error.code === "TASK_SESSION_UNATTACHED")
+            return null;
+        throw error;
+    });
+    if (attached?.status === "active" && attached.task.debug !== undefined)
+        await tasks.debugService().interrupt(attached.task.id, sessionId, nativeInput);
+}
+/** Close only the task attached to a native host's verified session. */
+export async function closeDebugSession(root, sessionId, host = "claude") {
+    if (!foregroundClockSupported(host))
+        return;
+    if (sessionId.length === 0)
+        return;
+    const saved = await readWorktreeRecord(join(root, ".worktrees", sessionWorktreeName(sessionId)));
+    const contextRoot = saved?.mainRoot === root && saved.sessionId === sessionId ? saved.path : root;
+    const tasks = new TaskService(new FileTaskStore(join(contextRoot, ".agent-ops/tasks/state.json"), contextRoot), { completion: { root: contextRoot, gitRunner: gitRunner(contextRoot), loadConfig: async () => (await loadEffectiveConfig(contextRoot, "project")).config } });
+    const attached = await tasks.status({ sessionId }).catch(() => null);
+    if (attached?.status === "active" && attached.task.debug !== undefined)
+        await tasks.debugService().foregroundStop(attached.task.id, sessionId);
+}
+/**
+ * Without the completion gate, an active DEBUG issue still cannot end a turn
+ * unless a current runtime stop checkpoint exists. Sessions without one pass.
+ */
+export function debugStopGate(root, rootConfig) {
+    return { handle: async (event) => {
+            if (event.event !== "stop" || event.sessionId === undefined || event.sessionId.length === 0 ||
+                event.terminationReason !== "model_stop" || event.fullyIdle !== true)
+                return null;
+            const sessionId = event.sessionId;
+            const evaluate = async (attempt) => {
+                const saved = await readWorktreeRecord(join(root, ".worktrees", sessionWorktreeName(sessionId))).catch(() => null);
+                const contextRoot = saved?.mainRoot === root && saved.sessionId === sessionId ? saved.path : root;
+                const config = contextRoot === root && attempt === 0 ? rootConfig : (await loadEffectiveConfig(contextRoot, "project")).config;
+                const runner = gitRunner(contextRoot);
+                const tasks = new TaskService(new FileTaskStore(join(contextRoot, ".agent-ops/tasks/state.json"), contextRoot), { completion: { root: contextRoot, gitRunner: runner, loadConfig: async () => config } });
+                const attached = await tasks.status({ sessionId }).catch(error => {
+                    if (error instanceof AgentOpsError && error.code === "TASK_SESSION_UNATTACHED")
+                        return null;
+                    throw error;
+                });
+                if (attached?.status !== "active" || attached.task.debug === undefined)
+                    return null;
+                await tasks.debugService().prepareStop(attached.task.id, sessionId);
+                const surface = await collectChangeSurface(runner);
+                const fingerprint = await calculateSourceFingerprint(contextRoot, { mode: "worktree", changedFiles: surface.paths }, runner);
+                return await tasks.debugService().validCheckpoint(attached.task.id, sessionId, fingerprint)
+                    ? { action: "continue", status: "UNKNOWN", code: "COMPLETION_GATE_TASK_DEBUG_STOPPED", remedy: "Original issue remains active with a runtime-bound non-success checkpoint." }
+                    : { action: "block", status: "FAIL", code: "COMPLETION_GATE_TASK_DEBUG_ACTIVE", remedy: "Continue the original DEBUG investigation, repair, verification and review loop. Failure to reproduce and an arbitrary checkpoint do not permit stopping. Preserve the task and budgets; record a current runtime stop checkpoint only for a proven blocker or exhausted limits." };
+            };
+            // Reload the task/config once for a transient gate fault; never rewrite bad evidence.
+            for (let attempt = 0; attempt < 2; attempt++) {
+                try {
+                    return await evaluate(attempt);
+                }
+                catch (error) {
+                    if (attempt === 0)
+                        continue;
+                    const code = error instanceof AgentOpsError ? error.code : "IO_ERROR";
+                    return { action: "continue", status: "UNKNOWN", code: "TASK_DEBUG_GATE_UNAVAILABLE", remedy: `DEBUG remains incomplete: gate ${code} failed after one targeted reload. Preserve the original task, evidence and budgets; run agent-ops doctor and restore readable task/config evidence before resuming. No completion is attested.` };
+                }
+            }
+            return null;
+        } };
+}

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

@@ -14,12 +14,14 @@ import { evaluateWorktreeEnter } from "../../../runtime/src/parallel/enter.js";
 import { evaluateWorktreeWrite, resolveMainRoot } from "../../../runtime/src/parallel/guard.js";
 import { ensureSessionWorktree, recordSessionOrigin } from "../../../runtime/src/parallel/service.js";
 import { CompletionGateService } from "../../../runtime/src/hooks/completion-gate.js";
+import { closeDebugSession, debugStopGate, interruptDebugSession, routeDebugPrompt, startDebugSession } from "./debug-intake.js";
 import { TaskService } from "../../../runtime/src/task/service.js";
 import { FileTaskStore } from "../../../runtime/src/task/store.js";
 import { FileEvidenceStore } from "../../../runtime/src/verify/evidence.js";
 import { readWorktreeRecord } from "../../../runtime/src/parallel/service.js";
 import { FileRunRepository } from "../../../runtime/src/run/service.js";
 import { validateWorkerStopHandoff } from "../../../runtime/src/run/worker-gate.js";
+import { evaluateGuardrail } from "../../../runtime/src/guardrails/evaluate.js";
 import { STOP_VERIFICATION_ENV, StopVerificationService } from "../../../runtime/src/hooks/stop-service.js";
 import { NodeVerificationProcessRunner } from "../../../runtime/src/verify/spawn.js";
 import { normalizeHookInput, runHookCommand, HOOK_EVENTS } from "./commands/hook.js";
@@ -53,13 +55,19 @@ function parseInput(source) {
 }
 function withInjectedSession(harness, input) {
     const sessionId = process.env.AGENT_OPS_SESSION_ID;
-    return harness === "agy" &&
-        sessionId !== undefined &&
-        typeof input === "object" &&
-        input !== null &&
-        !Array.isArray(input)
-        ? { ...input, conversationId: sessionId }
-        : input;
+    const codexSession = sessionId ?? process.env.CODEX_THREAD_ID;
+    if ((harness !== "agy" && harness !== "codex") ||
+        typeof input !== "object" || input === null || Array.isArray(input))
+        return input;
+    const fields = input;
+    if (harness === "agy") {
+        return (typeof fields.conversationId === "string" && fields.conversationId.length > 0) || sessionId === undefined
+            ? input
+            : { ...fields, conversationId: sessionId };
+    }
+    return (typeof fields.session_id === "string" && fields.session_id.length > 0) || codexSession === undefined
+        ? input
+        : { ...fields, session_id: codexSession };
 }
 function writeHookOutput(io, output) {
     if (output.stdout.length > 0) {
@@ -225,7 +233,7 @@ function completionGateFor(root, config, gitRunner, harness) {
         config,
         gitRunner,
         ...(harness === undefined ? {} : { harness }),
-        taskService: new TaskService(new FileTaskStore(join(root, ".agent-ops", "tasks", "state.json"), root)),
+        taskService: new TaskService(new FileTaskStore(join(root, ".agent-ops", "tasks", "state.json"), root), { completion: { root, gitRunner, loadConfig: async () => config } }),
         evidenceStore: new FileEvidenceStore(root, root),
         forRoot: async (worktree) => {
             const outcome = await loadProjectHookConfig(worktree);
@@ -246,7 +254,7 @@ function completionGateFor(root, config, gitRunner, harness) {
  */
 async function closeOfficeSession(io, dependencies) {
     try {
-        if (process.env.AGENT_OPS_DISABLE === "1" || dependencies.office === undefined)
+        if (process.env.AGENT_OPS_DISABLE === "1")
             return 0;
         const input = parseInput(await readStdin(io.stdin));
         if (typeof input !== "object" || input === null || Array.isArray(input))
@@ -254,26 +262,95 @@ async function closeOfficeSession(io, dependencies) {
         const fields = input;
         const root = dependencies.root ?? (typeof fields.cwd === "string" ? fields.cwd : process.cwd());
         const outcome = await hookConfigOutcome(root, dependencies.loadConfig);
-        if (outcome.kind === "invalid" || outcome.config.features.office?.enabled !== true)
+        if (outcome.kind === "invalid")
             return 0;
-        await dependencies.office({
-            root, harness: "claude", event: "SessionEnd", input, validated: true,
-            ...(typeof fields.session_id === "string" ? { sessionId: fields.session_id } : {})
-        });
+        if (dependencies.office !== undefined && outcome.config.features.office?.enabled === true)
+            await dependencies.office({
+                root, harness: "claude", event: "SessionEnd", input, validated: true,
+                ...(typeof fields.session_id === "string" ? { sessionId: fields.session_id } : {})
+            });
+        if (typeof fields.session_id === "string")
+            await closeDebugSession(root, fields.session_id, "claude").catch(() => undefined);
     }
     catch {
         // Office never blocks a session, least of all one that is ending.
     }
     return 0;
 }
+/**
+ * A prompt submitted outside the project loop: Office records the turn's work
+ * starting, and command policy refuses a literal credential the way the loop
+ * does. Every runtime failure lets the prompt through.
+ */
+async function promptSubmitted(harness, io, dependencies) {
+    try {
+        if (process.env.AGENT_OPS_DISABLE === "1")
+            return 0;
+        const input = parseInput(await readStdin(io.stdin));
+        if (typeof input !== "object" || input === null || Array.isArray(input))
+            return 0;
+        const fields = input;
+        const root = dependencies.root ?? (typeof fields.cwd === "string" ? fields.cwd : process.cwd());
+        const outcome = await hookConfigOutcome(root, dependencies.loadConfig);
+        if (outcome.kind === "invalid")
+            return 0;
+        const config = outcome.config;
+        if (dependencies.office !== undefined && config.features.office?.enabled === true) {
+            await dependencies.office({
+                root, harness, event: "UserPromptSubmit", input, validated: true,
+                ...(typeof fields.session_id === "string" ? { sessionId: fields.session_id } : {})
+            }).catch(() => undefined);
+        }
+        if (config.profiles.length === 0)
+            return 0;
+        // ponytail: the loop's 64 KiB prompt bound; a larger prompt goes unchecked.
+        const prompt = fields.prompt;
+        if (typeof prompt !== "string" || prompt.length === 0 || prompt.length > 64 * 1024 || prompt.includes("\0"))
+            return 0;
+        if (evaluateGuardrail({ kind: "content", content: prompt, scope: root }).action !== "block") {
+            const context = await routeDebugPrompt(root, input, harness).catch(error => `DEBUG intake unavailable: ${error instanceof Error ? error.message : "preserve current state"}`);
+            if (context !== null)
+                io.writeStdout(harness === "claude" ? JSON.stringify({ hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: context } }) : context + "\n");
+            return 0;
+        }
+        if (!config.profiles.includes("guardrails") && !config.profiles.includes("loop") && !config.profiles.includes("run"))
+            return 0;
+        const reason = "agent-ops blocked a suspected secret.";
+        if (harness === "claude") {
+            io.writeStdout(JSON.stringify({ decision: "block", reason }));
+            return 0;
+        }
+        io.writeStderr(reason + "\n");
+        return 2;
+    }
+    catch {
+        return 0;
+    }
+}
 export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
     const [harness, event] = argv;
+    if (harness === "codex" && event === "Interrupt") {
+        try {
+            const raw = await readStdin(io.stdin), input = parseInput(raw);
+            if (typeof input !== "object" || input === null || Array.isArray(input))
+                return 0;
+            const fields = input;
+            if (typeof fields.session_id !== "string" || fields.session_id.length === 0)
+                return 0;
+            const root = dependencies.root ?? (typeof fields.cwd === "string" ? fields.cwd : process.cwd());
+            await interruptDebugSession(root, fields.session_id, raw);
+        }
+        catch {
+            io.writeStdout(JSON.stringify({ systemMessage: "agent-ops: DEBUG interrupt progress could not be sealed; preserve the task and run agent-ops doctor before resuming." }));
+        }
+        return 0;
+    }
     if (harness === "claude" && event === "SessionEnd")
         return await closeOfficeSession(io, dependencies);
-    // Both hosts whose Stop hook can actually refuse a stop. codex never fires
-    // Stop under `codex exec` and rejects `permissionDecision:ask`, so its
-    // escape hatch could not be user-approved; opencode can only deny a tool
-    // call, never a stop.
+    if ((harness === "claude" || harness === "codex") && event === "UserPromptSubmit")
+        return await promptSubmitted(harness, io, dependencies);
+    // The generic completion gate requires an approval escape hatch. Codex
+    // only enforces DEBUG through runtime checkpoints and native human control.
     const completionGateInstalled = (harness === "agy" || harness === "claude") &&
         event === "Stop" &&
         argv.includes("--completion-gate");
@@ -322,8 +399,19 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
                 root = inputRoot;
             }
         }
-        const configOutcome = await hookConfigOutcome(root, dependencies.loadConfig);
+        let configOutcome = await hookConfigOutcome(root, dependencies.loadConfig);
+        const nativeStop = normalizeHookInput(harnessId, parsedInput);
+        if (harnessId === "codex" && hookEvent === "Stop" && configOutcome.kind === "invalid")
+            configOutcome = await hookConfigOutcome(root, dependencies.loadConfig);
         if (configOutcome.kind === "invalid") {
+            if (harnessId === "codex" && nativeStop?.event === "stop" && nativeStop.sessionId !== undefined) {
+                writeHookOutput(io, harnessDescriptor(harnessId).runtime.formatOutput("Stop", {
+                    action: "continue", status: "UNKNOWN", code: "TASK_DEBUG_GATE_UNAVAILABLE",
+                    remedy: "DEBUG remains incomplete: configuration failed after one targeted reload. Preserve the task, evidence and budgets; fix .agent-ops/config.json and run agent-ops doctor. No completion is attested."
+                }));
+                await closeDebugSession(root, nativeStop.sessionId, harnessId).catch(() => undefined);
+                return 0;
+            }
             if (completionGateInstalled) {
                 writeHookOutput(io, harnessDescriptor(harness).runtime.formatOutput("Stop", {
                     action: "block",
@@ -346,6 +434,15 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
             return 0;
         }
         const config = configOutcome.config;
+        if (harnessId === "codex" && hookEvent === "Stop" && nativeStop !== null && config.features.debug?.enabled === true) {
+            const result = await debugStopGate(root, config).handle(nativeStop);
+            if (result !== null) {
+                writeHookOutput(io, harnessDescriptor(harnessId).runtime.formatOutput("Stop", result));
+                if (result.action === "continue" && nativeStop.sessionId !== undefined)
+                    await closeDebugSession(root, nativeStop.sessionId, harnessId).catch(() => undefined);
+                return 0;
+            }
+        }
         if (completionGateInstalled && !config.features.completionGate.enabled) {
             writeHookOutput(io, harnessDescriptor(harness).runtime.formatOutput("Stop", {
                 action: "block",
@@ -359,8 +456,10 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
             ? await repositoryTrust(root, config, cliVersion)
             : await dependencies.trust(root, config, cliVersion);
         const trusted = trustStatus === "TRUSTED";
+        const normalized = normalizeHookInput(harnessId, parsedInput);
+        if (normalized?.event === "session-start" && normalized.sessionId !== undefined)
+            await startDebugSession(root, normalized.sessionId, harnessId).catch(() => undefined);
         if (dependencies.office !== undefined && config.features.office?.enabled === true) {
-            const normalized = normalizeHookInput(harnessId, parsedInput);
             if (normalized !== null) {
                 const phase = officePhaseHint(normalized);
                 void dependencies.office({
@@ -452,21 +551,43 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
                 await recordSessionOrigin(dependencies.worktree, { cwd: root, sessionId }).catch(() => undefined);
             }
         }
-        const output = await runHookCommand({
-            harness: harness,
-            event: hookEvent,
-            stdin: rawInput,
-            config,
-            trusted,
-            ...(worktreeGuard === undefined ? {} : { worktreeGuard }),
-            ...(worktreeEnter === undefined ? {} : { worktreeEnter }),
-            ...(dependencies.advisory === undefined
-                ? {}
-                : { advisory: dependencies.advisory }),
-            ...(stopVerification === undefined ? {} : { stopVerification }),
-            ...(completionGate === undefined ? {} : { completionGate })
-        });
+        let hookResult;
+        // Without the gate, DEBUG still refuses a Stop that has no valid stop
+        // checkpoint. Its own failure stays advisory, so it never blocks other work.
+        const debugStop = completionGate === undefined && hookEvent === "Stop" && normalized !== null &&
+            (harnessId === "agy" || harnessId === "claude" || harnessId === "codex") && config.features.debug?.enabled === true
+            ? await debugStopGate(root, config).handle(normalized)
+            : null;
+        if (debugStop !== null)
+            hookResult = debugStop;
+        const output = debugStop !== null
+            ? harnessDescriptor(harnessId).runtime.formatOutput("Stop", debugStop)
+            : await runHookCommand({
+                harness: harness,
+                event: hookEvent,
+                stdin: rawInput,
+                input: parsedInput,
+                config,
+                trusted,
+                onResult: result => { hookResult = result; },
+                ...(worktreeGuard === undefined ? {} : { worktreeGuard }),
+                ...(worktreeEnter === undefined ? {} : { worktreeEnter }),
+                ...(dependencies.advisory === undefined
+                    ? {}
+                    : { advisory: dependencies.advisory }),
+                ...(stopVerification === undefined ? {} : { stopVerification }),
+                ...(completionGate === undefined ? {} : { completionGate })
+            });
         writeHookOutput(io, output);
+        // A Stop can be advisory or gated, but the foreground clock only ends on
+        // the same trusted idle model_stop that the native decision accepted.
+        if (normalized?.event === "stop" &&
+            normalized.sessionId !== undefined &&
+            normalized.terminationReason === "model_stop" &&
+            normalized.fullyIdle === true &&
+            hookResult?.action === "continue") {
+            await closeDebugSession(root, normalized.sessionId, harnessId).catch(() => undefined);
+        }
     }
     catch {
         if (completionGateInstalled) {

package/dist/packages/cli/src/office-entry.js

@@ -7,7 +7,7 @@ import { spawn } from "node:child_process";
 import { collectOfficeBuilding } from "../../../runtime/src/office/collect.js";
 import { claimOffice, createOfficeServer, ensureOffice, legacyOfficeHome, officeRecordPath, readLiveOffice, officeUrl, releaseOffice, userOfficeHome } from "../../../runtime/src/office/server.js";
 import { registerOfficeRepo } from "../../../runtime/src/office/repos.js";
-import { recordOfficeSession } from "../../../runtime/src/office/sessions.js";
+import { recordOfficeSession, recordOfficeSessionPhase } from "../../../runtime/src/office/sessions.js";
 import { resolveCheckouts } from "../../../runtime/src/parallel/service.js";
 import { createLaunchdDescriptor, LaunchdController } from "../../../runtime/src/run/macOS.js";
 import { ensurePrivateDirectory, readPrivateFile } from "../../../runtime/src/security/permissions.js";
@@ -47,8 +47,11 @@ function sessionIdentity(options) {
     const nested = recordValue(options.input, "input");
     return firstText(options.sessionId, recordValue(options.input, "session_id"), recordValue(options.input, "sessionId"), recordValue(options.input, "conversationId"), recordValue(options.input, "thread_id"), recordValue(options.input, "threadId"), recordValue(nested, "sessionID"), recordValue(nested, "session_id"), process.env.AGENT_OPS_SESSION_ID, process.env.CODEX_THREAD_ID);
 }
-function officeEvent(event) {
-    return event === "SessionStart" ? "start" : event === "Stop" ? "stop" : event === "SessionEnd" ? "end" : "activity";
+/** agy's SessionStart is its native PreInvocation, sent as each invocation's work begins. */
+export function officeEvent(harness, event) {
+    if (event === "SessionStart")
+        return harness === "agy" ? "activity" : "start";
+    return event === "Stop" ? "stop" : event === "SessionEnd" ? "end" : "activity";
 }
 /** Phase hints come only from normalized native event kinds and exact agent-ops argv. */
 export function officePhaseHint(event) {
@@ -64,13 +67,14 @@ export function officePhaseHint(event) {
         if (basename(command.command) !== "agent-ops")
             continue;
         const action = command.args[0];
-        const next = action === "verify"
+        // batch and advance report their later steps themselves; this is their first.
+        const next = action === "verify" || action === "batch"
             ? "verifying"
             : action === "review"
                 ? "reviewing"
                 : action === "worktree" && command.args[1] === "finish"
                     ? "integrating"
-                    : action === "task" && command.args[1] === "complete"
+                    : action === "task" && (command.args[1] === "complete" || command.args[1] === "advance")
                         ? "integrating"
                         : action === "task"
                             ? "planning"
@@ -117,7 +121,7 @@ export async function observeOfficeSession(options) {
             harness: options.harness,
             projectRoot: mainRoot,
             commonDir,
-            event: officeEvent(options.event),
+            event: officeEvent(options.harness, options.event),
             ...(options.agentId === undefined ? {} : { agentId: options.agentId }),
             ...(process.env.AGENT_OPS_RUN_ID === undefined ? {} : { runId: process.env.AGENT_OPS_RUN_ID }),
             ...(process.env.AGENT_OPS_WORKER_ID === undefined ? {} : { workerId: process.env.AGENT_OPS_WORKER_ID }),
@@ -136,6 +140,30 @@ export async function observeOfficeSession(options) {
         // Office is display-only; a missing Git checkout, lock or launcher never blocks a host hook.
     }
 }
+/**
+ * Moves these sessions' people as a batch or advance reaches each step.
+ * Display only: a disabled Office, an unknown session or a failed write records nothing.
+ */
+export async function officePhaseReporter(cwd, sessionIds) {
+    const none = async () => { };
+    try {
+        if (sessionIds.length === 0 || !(await officeEnabled(cwd)))
+            return none;
+        const { commonDir } = await checkouts(cwd);
+        // One write at a time, in order, so the latest step is the one that stays.
+        let chain = Promise.resolve();
+        return async (phase) => {
+            chain = chain.then(async () => {
+                for (const sessionId of sessionIds)
+                    await recordOfficeSessionPhase(commonDir, sessionId, phase).catch(() => { });
+            });
+            await chain;
+        };
+    }
+    catch {
+        return none;
+    }
+}
 async function checkouts(cwd) {
     return await resolveCheckouts(worktreeDependencies(), cwd);
 }

package/dist/packages/cli/src/run-deps.js

@@ -13,6 +13,7 @@ import { FileRunRepository, RunService } from "../../../runtime/src/run/service.
 import { readPrivateFile, writePrivateFile } from "../../../runtime/src/security/permissions.js";
 import { collectChangeSurface } from "../../../runtime/src/verify/change-surface.js";
 import { worktreeDependencies, gitRunner, trustStore } from "./parallel-deps.js";
+import { officePhaseReporter } from "./office-entry.js";
 import { NativeRunTransport } from "../../../runtime/src/run/transport.js";
 import { ClaudeGoalHost } from "../../../runtime/src/run/hosts/claude.js";
 import { CodexGoalHost } from "../../../runtime/src/run/hosts/codex.js";
@@ -145,6 +146,13 @@ export async function runPhaseObserver(cwd, runId, workerId) {
     const repository = new FileRunRepository(join(commonDir, "agent-ops", "runs"), commonDir);
     return async (phase, progress) => await recordRunPhase(repository, runId, workerId, phase, progress);
 }
+/** A run worker's advance reports to its run; an ordinary session's moves its own person in Office. */
+export async function advancePhaseObserver(cwd, sessionId, env = process.env) {
+    if (env.AGENT_OPS_RUN_ID !== undefined && env.AGENT_OPS_WORKER_ID !== undefined)
+        return await runPhaseObserver(cwd, env.AGENT_OPS_RUN_ID, env.AGENT_OPS_WORKER_ID);
+    const office = await officePhaseReporter(cwd, sessionId === undefined ? [] : [sessionId]);
+    return async (phase) => await office(phase);
+}
 export const runEntry = fileURLToPath(new URL("./run-entry.js", import.meta.url));
 export function runDescriptor(state) {
     return createLaunchdDescriptor({ runId: state.runId, workerId: "supervisor", privateDirectory: join(state.commonDir, "agent-ops", "runs", state.runId),