lazycodex-ai 5.0.0-beta.57 → 5.0.0-beta.61

package/packages/omo-codex/plugin/components/ulw-loop/dist/sdk/factory.js

@@ -0,0 +1,141 @@
+import { checkpointUlwLoop } from "../checkpoint.js";
+import { checkpointTemplate } from "../checkpoint-template.js";
+import { recordEvidence } from "../evidence.js";
+import { ulwLoopAttemptEvidenceDir } from "../paths.js";
+import { addUlwLoopGoal, createUlwLoopPlan, startNextUlwLoop, summarizeUlwLoopPlan } from "../plan-crud.js";
+import { readUlwLoopPlan } from "../plan-io.js";
+import { recordFinalReviewBlockers } from "../review-blockers.js";
+import { UlwLoopError } from "../runtime.js";
+import { statusNextActions } from "../status-next-actions.js";
+import { steerUlwLoop } from "../steering.js";
+import { ULW_LOOP_MANIFEST } from "./manifest.js";
+// The SDK takes inline values only, so a snapshot that is not JSON is a caller error - normalize it
+// to the same stable code the CLI reports instead of letting it surface as a generic failure.
+function validateCodexGoalJson(raw) {
+    if (raw === undefined)
+        return;
+    try {
+        JSON.parse(raw);
+    }
+    catch (error) {
+        throw new UlwLoopError(`Invalid codexGoal: ${error instanceof Error ? error.message : "not valid JSON"}`, "ULW_LOOP_CODEX_GOAL_JSON_INVALID", { cause: error });
+    }
+}
+function validateContext(context) {
+    if (!context.cwd.trim())
+        throw new UlwLoopError("cwd is required.", "ULW_LOOP_CWD_REQUIRED");
+    if (!context.sessionId.trim())
+        throw new UlwLoopError("ULW_LOOP_SESSION_ID_REQUIRED: sessionId is required.", "ULW_LOOP_SESSION_ID_REQUIRED");
+    if (context.surface !== "omo-senpi" && context.surface !== "lazycodex")
+        throw new UlwLoopError("surface must be omo-senpi or lazycodex.", "ULW_LOOP_SURFACE_INVALID");
+}
+function errorDetails(error) {
+    const details = error.details === undefined
+        ? undefined
+        : Object.fromEntries(Object.entries(error.details).map(([key, value]) => [key, String(value)]));
+    return details === undefined
+        ? { code: error.code, message: error.message }
+        : { code: error.code, message: error.message, details };
+}
+function failure(operation, error) {
+    return { ok: false, operation, error: errorDetails(error) };
+}
+function caught(operation, error) {
+    return failure(operation, error instanceof UlwLoopError ? error : new UlwLoopError(error.message, "ULW_LOOP_ERROR"));
+}
+function isKnownRequest(request) {
+    return ULW_LOOP_MANIFEST.operations.some((operation) => operation.name === request.operation);
+}
+function unreachable(value) {
+    throw new UlwLoopError(`Unhandled operation: ${String(value)}`, "ULW_LOOP_OPERATION_UNHANDLED");
+}
+function nextActionsFrom(result) {
+    if (!("nextActions" in result) || !Array.isArray(result.nextActions))
+        return [];
+    return result.nextActions.filter((action) => typeof action === "string").slice(0, 8);
+}
+function checkpointWithValidatedSnapshot(context, scope, args) {
+    validateCodexGoalJson(args.codexGoalJson);
+    return checkpointUlwLoop(context.cwd, args, scope, { surface: context.surface });
+}
+export function createAgentToolkit(context, deps = {}) {
+    validateContext(context);
+    const scope = { sessionId: context.sessionId };
+    const notify = async (operation, response) => {
+        if (deps.hooks?.onOperation !== undefined)
+            await deps.hooks.onOperation({ operation, context, response });
+        return response;
+    };
+    const invoke = async (operation, fn) => {
+        try {
+            const result = await fn();
+            const nextActions = typeof result === "object" && result !== null ? nextActionsFrom(result) : [];
+            return await notify(operation, { ok: true, operation, result, nextActions });
+        }
+        catch (error) {
+            const response = caught(operation, error instanceof Error ? error : new Error("ULW_LOOP_ERROR"));
+            return notify(operation, response);
+        }
+    };
+    const toolkit = {
+        dispatch: async (request) => {
+            if (!isKnownRequest(request))
+                return failure(request.operation, new UlwLoopError(`Unknown operation: ${request.operation}`, "ULW_LOOP_OPERATION_UNKNOWN"));
+            switch (request.operation) {
+                case "help":
+                    return toolkit.help();
+                case "create-goals":
+                    return toolkit.createGoals(request.args);
+                case "status":
+                    return toolkit.status();
+                case "complete-goals":
+                    return toolkit.completeGoals(request.args);
+                case "checkpoint":
+                    return toolkit.checkpoint(request.args);
+                case "steer":
+                    return toolkit.steer(request.args);
+                case "add-goal":
+                    return toolkit.addGoal(request.args);
+                case "criteria":
+                    return toolkit.criteria(request.args);
+                case "record-evidence":
+                    return toolkit.recordEvidence(request.args);
+                case "record-review-blockers":
+                    return toolkit.recordReviewBlockers(request.args);
+                default:
+                    return unreachable(request);
+            }
+        },
+        help: () => invoke("help", async () => ULW_LOOP_MANIFEST),
+        createGoals: (args) => invoke("create-goals", () => createUlwLoopPlan(context.cwd, args, scope)),
+        status: () => invoke("status", async () => {
+            const plan = await readUlwLoopPlan(context.cwd, scope);
+            const active = plan.goals.find((goal) => goal.id === plan.activeGoalId);
+            return {
+                plan,
+                summary: summarizeUlwLoopPlan(plan),
+                nextActions: statusNextActions(plan),
+                // Attempt directories are an evidence-layout v2 concept; a v1 plan must not advertise one.
+                ...(active === undefined || plan.evidenceLayoutVersion !== 2
+                    ? {}
+                    : { currentAttemptDir: ulwLoopAttemptEvidenceDir(active.id, active.attempt, scope) }),
+            };
+        }),
+        completeGoals: (args = {}) => invoke("complete-goals", () => startNextUlwLoop(context.cwd, args, scope)),
+        checkpoint: (args) => invoke("checkpoint", () => args.printTemplate === true
+            ? checkpointTemplate(context.cwd, scope, args.goalId, { surface: context.surface })
+            : checkpointWithValidatedSnapshot(context, scope, args)),
+        steer: (args) => invoke("steer", () => steerUlwLoop(context.cwd, args, scope)),
+        addGoal: (args) => invoke("add-goal", () => addUlwLoopGoal(context.cwd, args, scope)),
+        criteria: (args) => invoke("criteria", async () => {
+            const plan = await readUlwLoopPlan(context.cwd, scope);
+            const goal = plan.goals.find((candidate) => candidate.id === args.goalId);
+            if (goal === undefined)
+                throw new UlwLoopError(`Unknown ulw-loop id: ${args.goalId}.`, "ULW_LOOP_GOAL_NOT_FOUND");
+            return { goalId: goal.id, criteria: goal.successCriteria };
+        }),
+        recordEvidence: (args) => invoke("record-evidence", () => recordEvidence(context.cwd, args, scope)),
+        recordReviewBlockers: (args) => invoke("record-review-blockers", () => recordFinalReviewBlockers(context.cwd, args, scope)),
+    };
+    return toolkit;
+}

package/packages/omo-codex/plugin/components/ulw-loop/dist/sdk/manifest.d.ts

@@ -0,0 +1,46 @@
+export declare const ULW_LOOP_OPERATIONS: readonly ["help", "create-goals", "status", "complete-goals", "checkpoint", "steer", "add-goal", "criteria", "record-evidence", "record-review-blockers"];
+export type UlwLoopOperation = (typeof ULW_LOOP_OPERATIONS)[number];
+export interface ToolkitOperationManifest {
+    readonly name: UlwLoopOperation;
+    readonly mutating: boolean;
+}
+export interface ToolkitManifest {
+    readonly version: 1;
+    readonly name: "ulw-loop";
+    readonly operations: readonly ToolkitOperationManifest[];
+}
+export declare const ULW_LOOP_MANIFEST: {
+    version: 1;
+    name: "ulw-loop";
+    operations: ({
+        name: "help";
+        mutating: false;
+    } | {
+        name: "create-goals";
+        mutating: true;
+    } | {
+        name: "status";
+        mutating: false;
+    } | {
+        name: "complete-goals";
+        mutating: true;
+    } | {
+        name: "checkpoint";
+        mutating: true;
+    } | {
+        name: "steer";
+        mutating: true;
+    } | {
+        name: "add-goal";
+        mutating: true;
+    } | {
+        name: "criteria";
+        mutating: false;
+    } | {
+        name: "record-evidence";
+        mutating: true;
+    } | {
+        name: "record-review-blockers";
+        mutating: true;
+    })[];
+};

package/packages/omo-codex/plugin/components/ulw-loop/dist/sdk/manifest.js

@@ -0,0 +1,28 @@
+export const ULW_LOOP_OPERATIONS = [
+    "help",
+    "create-goals",
+    "status",
+    "complete-goals",
+    "checkpoint",
+    "steer",
+    "add-goal",
+    "criteria",
+    "record-evidence",
+    "record-review-blockers",
+];
+export const ULW_LOOP_MANIFEST = {
+    version: 1,
+    name: "ulw-loop",
+    operations: [
+        { name: "help", mutating: false },
+        { name: "create-goals", mutating: true },
+        { name: "status", mutating: false },
+        { name: "complete-goals", mutating: true },
+        { name: "checkpoint", mutating: true },
+        { name: "steer", mutating: true },
+        { name: "add-goal", mutating: true },
+        { name: "criteria", mutating: false },
+        { name: "record-evidence", mutating: true },
+        { name: "record-review-blockers", mutating: true },
+    ],
+};

package/packages/omo-codex/plugin/components/ulw-loop/dist/sdk/types.d.ts

@@ -0,0 +1,127 @@
+import type { CheckpointUlwLoopArgs, CheckpointUlwLoopResult } from "../checkpoint.js";
+import type { CheckpointTemplate } from "../checkpoint-template.js";
+import type { recordEvidence } from "../evidence.js";
+import type { addUlwLoopGoal, createUlwLoopPlan, startNextUlwLoop, summarizeUlwLoopPlan } from "../plan-crud.js";
+import type { recordFinalReviewBlockers } from "../review-blockers.js";
+import type { steerUlwLoop } from "../steering.js";
+import type { UlwLoopSteeringProposal } from "../steering-types.js";
+import type { UlwLoopToolkitSurface } from "../surface.js";
+import type { UlwLoopPlan } from "../types.js";
+import type { ULW_LOOP_MANIFEST, UlwLoopOperation } from "./manifest.js";
+export type ToolkitSurface = UlwLoopToolkitSurface;
+export interface ToolkitContext {
+    readonly cwd: string;
+    readonly sessionId: string;
+    readonly surface: ToolkitSurface;
+}
+export type CreateGoalsArgs = Parameters<typeof createUlwLoopPlan>[1];
+export type CompleteGoalsArgs = NonNullable<Parameters<typeof startNextUlwLoop>[1]>;
+export type SteerArgs = UlwLoopSteeringProposal;
+export type AddGoalArgs = Parameters<typeof addUlwLoopGoal>[1];
+export type RecordEvidenceArgs = Parameters<typeof recordEvidence>[1];
+export type CriteriaArgs = {
+    readonly goalId: string;
+};
+export type CheckpointMutationArgs = CheckpointUlwLoopArgs & {
+    readonly printTemplate?: false;
+};
+export type CheckpointTemplateArgs = {
+    readonly printTemplate: true;
+    readonly goalId?: string;
+};
+export type CheckpointArgs = CheckpointMutationArgs | CheckpointTemplateArgs;
+export type RecordReviewBlockersArgs = Parameters<typeof recordFinalReviewBlockers>[1];
+export type ToolkitDispatchRequest = {
+    readonly operation: "help";
+    readonly args?: Record<never, never>;
+} | {
+    readonly operation: "create-goals";
+    readonly args: CreateGoalsArgs;
+} | {
+    readonly operation: "status";
+    readonly args?: Record<never, never>;
+} | {
+    readonly operation: "complete-goals";
+    readonly args?: CompleteGoalsArgs;
+} | {
+    readonly operation: "checkpoint";
+    readonly args: CheckpointArgs;
+} | {
+    readonly operation: "steer";
+    readonly args: SteerArgs;
+} | {
+    readonly operation: "add-goal";
+    readonly args: AddGoalArgs;
+} | {
+    readonly operation: "criteria";
+    readonly args: CriteriaArgs;
+} | {
+    readonly operation: "record-evidence";
+    readonly args: RecordEvidenceArgs;
+} | {
+    readonly operation: "record-review-blockers";
+    readonly args: RecordReviewBlockersArgs;
+};
+export interface ToolkitUnknownRequest {
+    readonly operation: string;
+    readonly args?: Record<never, never>;
+}
+export interface ToolkitError {
+    readonly code: string;
+    readonly message: string;
+    readonly details?: Readonly<Record<string, string>>;
+}
+export interface ToolkitSuccess<Operation extends UlwLoopOperation, Result> {
+    readonly ok: true;
+    readonly operation: Operation;
+    readonly result: Result;
+    readonly nextActions: readonly string[];
+    readonly warnings?: readonly string[];
+}
+export interface ToolkitFailure<Operation extends string = string> {
+    readonly ok: false;
+    readonly operation: Operation;
+    readonly error: ToolkitError;
+}
+type StatusResult = {
+    readonly plan: UlwLoopPlan;
+    readonly summary: ReturnType<typeof summarizeUlwLoopPlan>;
+    readonly nextActions: readonly string[];
+    readonly currentAttemptDir?: string;
+};
+type ResultFor<Operation extends UlwLoopOperation> = Operation extends "help" ? typeof ULW_LOOP_MANIFEST : Operation extends "create-goals" ? Awaited<ReturnType<typeof createUlwLoopPlan>> : Operation extends "status" ? StatusResult : Operation extends "complete-goals" ? Awaited<ReturnType<typeof startNextUlwLoop>> : Operation extends "checkpoint" ? CheckpointUlwLoopResult | CheckpointTemplate : Operation extends "steer" ? Awaited<ReturnType<typeof steerUlwLoop>> : Operation extends "add-goal" ? Awaited<ReturnType<typeof addUlwLoopGoal>> : Operation extends "criteria" ? {
+    readonly goalId: string;
+    readonly criteria: UlwLoopPlan["goals"][number]["successCriteria"];
+} : Operation extends "record-evidence" ? Awaited<ReturnType<typeof recordEvidence>> : Operation extends "record-review-blockers" ? Awaited<ReturnType<typeof recordFinalReviewBlockers>> : never;
+export type ToolkitResultFor<Operation extends UlwLoopOperation> = ResultFor<Operation>;
+export type ToolkitResponseFor<Operation extends UlwLoopOperation> = ToolkitSuccess<Operation, ResultFor<Operation>> | ToolkitFailure<Operation>;
+export type ToolkitOperationResponse = {
+    [Operation in UlwLoopOperation]: ToolkitResponseFor<Operation>;
+}[UlwLoopOperation];
+export type ToolkitDispatchResponse = ToolkitOperationResponse | ToolkitFailure<string>;
+export type ToolkitResponse<Result> = ToolkitSuccess<UlwLoopOperation, Result> | ToolkitFailure<string>;
+export interface ToolkitOperationHookEvent<Operation extends UlwLoopOperation = UlwLoopOperation> {
+    readonly operation: Operation;
+    readonly context: ToolkitContext;
+    readonly response: ToolkitResponseFor<Operation>;
+}
+export interface ToolkitHostHooks {
+    readonly onOperation?: <Operation extends UlwLoopOperation>(event: ToolkitOperationHookEvent<Operation>) => void | Promise<void>;
+}
+export interface AgentToolkitDependencies {
+    readonly hooks?: ToolkitHostHooks;
+}
+export interface AgentToolkit {
+    readonly dispatch: (request: ToolkitDispatchRequest | ToolkitUnknownRequest) => Promise<ToolkitDispatchResponse>;
+    readonly help: () => Promise<ToolkitResponseFor<"help">>;
+    readonly createGoals: (args: CreateGoalsArgs) => Promise<ToolkitResponseFor<"create-goals">>;
+    readonly status: () => Promise<ToolkitResponseFor<"status">>;
+    readonly completeGoals: (args?: CompleteGoalsArgs) => Promise<ToolkitResponseFor<"complete-goals">>;
+    readonly checkpoint: (args: CheckpointArgs) => Promise<ToolkitResponseFor<"checkpoint">>;
+    readonly steer: (args: SteerArgs) => Promise<ToolkitResponseFor<"steer">>;
+    readonly addGoal: (args: AddGoalArgs) => Promise<ToolkitResponseFor<"add-goal">>;
+    readonly criteria: (args: CriteriaArgs) => Promise<ToolkitResponseFor<"criteria">>;
+    readonly recordEvidence: (args: RecordEvidenceArgs) => Promise<ToolkitResponseFor<"record-evidence">>;
+    readonly recordReviewBlockers: (args: RecordReviewBlockersArgs) => Promise<ToolkitResponseFor<"record-review-blockers">>;
+}
+export {};

package/packages/omo-codex/plugin/components/ulw-loop/dist/sdk/types.js

@@ -0,0 +1 @@
+export {};

package/packages/omo-codex/plugin/components/ulw-loop/dist/sdk.d.ts

@@ -0,0 +1,3 @@
+export { createAgentToolkit } from "./sdk/factory.js";
+export * from "./sdk/manifest.js";
+export * from "./sdk/types.js";

package/packages/omo-codex/plugin/components/ulw-loop/dist/sdk.js

@@ -0,0 +1,3 @@
+export { createAgentToolkit } from "./sdk/factory.js";
+export * from "./sdk/manifest.js";
+export * from "./sdk/types.js";

package/packages/omo-codex/plugin/components/ulw-loop/dist/spawn-guard.d.ts

@@ -4,5 +4,6 @@ export interface SpawnGuardOptions {
     readonly lockTimeoutMs?: number;
 }
 export declare function applySpawnGuards(payload: PreToolUsePayload, options?: SpawnGuardOptions): string;
+export declare function applySpawnBudgetGuards(payload: PreToolUsePayload, options?: SpawnGuardOptions): string;
 export declare function runSpawnAdmissionRecorderCli(stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream): Promise<void>;
 export declare function runSpawnGuardCli(stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream): Promise<void>;

package/packages/omo-codex/plugin/components/ulw-loop/dist/spawn-guard.js

@@ -4,12 +4,18 @@ import { dirname, join } from "node:path";
 import { parsePreToolUsePayload } from "./codex-hook.js";
 import { isFinalRunCompletionCandidate } from "./goal-status.js";
 import { ulwLoopAttemptEvidenceDir, ulwLoopDir, ulwLoopStateLockPath } from "./paths.js";
+import { spawnRoleDenial } from "./spawn-role-guard.js";
 import { isStateLockTimeout, withStateLockSync } from "./state-lock.js";
 import { GATE_REVIEWER_AGENT_NAMES, REVIEWER_ROLES_BY_SURFACE, resolveToolkitSurface, reviewerRolesFor, } from "./surface.js";
 // spawn_agent = v1; collaborationspawn_agent = the delimiter-free flattened v2
 // hook token from codex-rs hook_names.rs; collaboration.spawn_agent = the
 // dotted token observed live in the task-1 probe (hook-tool-tokens.txt).
-const SPAWN_TOOL_TOKENS = new Set(["spawn_agent", "collaborationspawn_agent", "collaboration.spawn_agent"]);
+const SPAWN_TOOL_TOKENS = new Set([
+    "spawn_agent",
+    "multi_agent_v1.spawn_agent",
+    "collaborationspawn_agent",
+    "collaboration.spawn_agent",
+]);
 export const DEFAULT_FANOUT_LIMIT = 24;
 const DEFAULT_REVIEW_SPAWN_LIMIT = 3;
 const GATE_MESSAGE_PATTERN = /lazycodex-gate-reviewer|omo-senpi-gate-reviewer|final gate review/i;
@@ -20,6 +26,16 @@ const REVIEW_AGENT_TYPES = [
 ];
 const REVIEW_AGENT_TYPE_SET = new Set(REVIEW_AGENT_TYPES);
 export function applySpawnGuards(payload, options = {}) {
+    if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name))
+        return "";
+    if (resolveToolkitSurface() === "lazycodex") {
+        const reason = spawnRoleDenial(payload.tool_input);
+        if (reason !== null)
+            return deny(reason);
+    }
+    return applySpawnBudgetGuards(payload, options);
+}
+export function applySpawnBudgetGuards(payload, options = {}) {
     if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name))
         return "";
     const breaker = readAdmissionBreaker(payload.session_id);
@@ -93,15 +109,16 @@ export async function runSpawnGuardCli(stdin, stdout) {
         for await (const chunk of stdin)
             chunks.push(Buffer.from(chunk));
         const payload = parsePreToolUsePayload(Buffer.concat(chunks).toString("utf8"));
-        if (payload === null)
+        if (payload === null) {
+            stdout.write(deny("LazyCodex spawn guard received an invalid hook payload; role routing was not verified."));
             return;
+        }
         const output = applySpawnGuards(payload);
         if (output.length > 0)
             stdout.write(output);
     }
     catch (error) {
-        if (error instanceof Error)
-            return;
+        stdout.write(deny(`LazyCodex spawn guard failed: ${error instanceof Error ? error.message : String(error)}`));
     }
 }
 // Read-only fan-out eligibility check. Returns a denial reason when the next

package/packages/omo-codex/plugin/components/ulw-loop/dist/spawn-role-guard.d.ts

@@ -0,0 +1,2 @@
+export declare const LAZYCODEX_SPAWN_ROLES: ReadonlySet<string>;
+export declare function spawnRoleDenial(input: unknown): string | null;

package/packages/omo-codex/plugin/components/ulw-loop/dist/spawn-role-guard.js

@@ -0,0 +1,22 @@
+// Explicit selectors, pinned by a test to the bundled role TOMLs. The generated
+// default is a non-fork fallback, not a selector: a user can opt out of owning it.
+export const LAZYCODEX_SPAWN_ROLES = new Set([
+    "explorer",
+    "lazycodex-clone-fidelity-reviewer",
+    "lazycodex-code-reviewer",
+    "lazycodex-gate-reviewer",
+    "lazycodex-qa-executor",
+    "lazycodex-worker-high",
+    "lazycodex-worker-low",
+    "lazycodex-worker-medium",
+    "librarian",
+    "metis",
+    "momus",
+    "plan",
+]);
+export function spawnRoleDenial(input) {
+    const role = typeof input === "object" && input !== null && "agent_type" in input ? input.agent_type : undefined;
+    if (typeof role === "string" && LAZYCODEX_SPAWN_ROLES.has(role))
+        return null;
+    return `LazyCodex requires an explicit registered agent_type: ${[...LAZYCODEX_SPAWN_ROLES].join(", ")}. Received ${JSON.stringify(role) ?? "no agent_type"}. Use the matching role and fork_turns: "none" (V2) or fork_context: false (V1), unless full history is deliberately required. The hook cannot see the tool schema; if agent_type is unavailable, stop and report incompatible role routing rather than spawning a generic agent. Describing a role in message does not select its TOML.`;
+}

package/packages/omo-codex/plugin/components/ulw-loop/hooks/hooks.json

@@ -7,20 +7,20 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook user-prompt-submit --with-ultrawork",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.57) Checking Ulw-Loop Steering"
+						"statusMessage": "(OmO 5.0.0-beta.61) Checking Ulw-Loop Steering"
 					}
 				]
 			}
 		],
 		"PostToolUse": [
 			{
-				"matcher": "^(spawn_agent|collaborationspawn_agent|collaboration\\.spawn_agent)$",
+				"matcher": "^(spawn_agent|multi_agent_v1\\.spawn_agent|collaborationspawn_agent|collaboration\\.spawn_agent)$",
 				"hooks": [
 					{
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook post-tool-use-spawn",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.57) Recording Spawn Admission"
+						"statusMessage": "(OmO 5.0.0-beta.61) Recording Spawn Admission"
 					}
 				]
 			}
@@ -33,18 +33,18 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.57) Enforcing Unlimited Ulw-Loop Budget"
+						"statusMessage": "(OmO 5.0.0-beta.61) Enforcing Unlimited Ulw-Loop Budget"
 					}
 				]
 			},
 			{
-				"matcher": "^(spawn_agent|collaborationspawn_agent|collaboration\\.spawn_agent)$",
+				"matcher": "^(spawn_agent|multi_agent_v1\\.spawn_agent|collaborationspawn_agent|collaboration\\.spawn_agent)$",
 				"hooks": [
 					{
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use-spawn",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.57) Guarding Ulw-Loop Spawns"
+						"statusMessage": "(OmO 5.0.0-beta.61) Guarding Ulw-Loop Spawns"
 					}
 				]
 			}
@@ -56,7 +56,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook stop",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.57) Checking Ulw-Loop Resume"
+						"statusMessage": "(OmO 5.0.0-beta.61) Checking Ulw-Loop Resume"
 					}
 				]
 			}

package/packages/omo-codex/plugin/components/ulw-loop/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-ulw-loop",
-	"version": "5.0.0-beta.57",
+	"version": "5.0.0-beta.61",
 	"description": "Codex plugin: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/ulw-loop/skills/ulw-loop/SKILL.md

@@ -68,3 +68,7 @@ Codex exposes ONE subagent surface per session — check your tool list. GPT-5.6
 V1 fallback (gpt-5.5, gpt-5.6-luna): `multi_agent_v1.spawn_agent({...,"fork_context":false})`, `multi_agent_v1.send_input` (re-task), `multi_agent_v1.wait_agent({"targets":[...],"timeout_ms":...})`, `multi_agent_v1.close_agent`.
 
 When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`.
+
+## Driver goal lifecycle
+
+The Codex thread goal is a DRIVER the loop instructs, never a gate. `checkpoint` takes an OPTIONAL `--codex-goal-json` snapshot, records it verbatim in the ledger, and never rejects on its status or objective; the advice arrives in `nextActions`. A driver completed early yields advice to `create_goal` again with the plan's objective verbatim; `paused`, `usage_limited`, and `budget_limited` yield resume advice; a differing objective is a warning, not a refusal. Malformed snapshot input is the only failure, reported as `ULW_LOOP_CODEX_GOAL_JSON_INVALID`.

package/packages/omo-codex/plugin/components/ulw-loop/src/checkpoint-template.ts

@@ -11,6 +11,10 @@ export interface CheckpointTemplate {
 	readonly guidance?: string;
 }
 
+export interface CheckpointTemplateDependencies {
+	readonly surface?: UlwLoopToolkitSurface;
+}
+
 function artifactPath(base: string, name: string): string {
 	return `${base}/${name}`;
 }
@@ -97,8 +101,10 @@ export async function checkpointTemplate(
 	repoRoot: string,
 	scope?: UlwLoopScope,
 	goalId?: string,
+	dependencies?: CheckpointTemplateDependencies,
 ): Promise<CheckpointTemplate> {
 	const plan: UlwLoopPlan = await readUlwLoopPlan(repoRoot, scope);
+	const surface = dependencies?.surface ?? resolveToolkitSurface();
 	const targetId = goalId ?? plan.activeGoalId;
 	const active = plan.goals.find((goal) => goal.id === targetId);
 	if (goalId !== undefined && active === undefined)
@@ -110,7 +116,7 @@ export async function checkpointTemplate(
 		"Fill every <replace:...> value with plausible non-empty evidence and use real, non-empty artifact files.",
 		'Passing codex-goal-json example: {"goal":{"objective":"<plan codexObjective verbatim>","status":"complete"}}.',
 		'Passing quality-gate-json example requires gateReview {"by":"category:deep","recommendation":"APPROVE","evidence":"review passed","reportPath":"<attemptDir>/gate-review.md","blockers":[],"notes":[]}, manualQa.artifactRefs objects, iteration, and criteriaCoverage.',
-		...(resolveToolkitSurface() === "lazycodex"
+		...(surface === "lazycodex"
 			? [
 					"Self-review defaults: manualQa.by and gateReview.by are main-session. Alternatives: manualQa.by accepts lazycodex-qa-executor; gateReview.by accepts lazycodex-gate-reviewer, category:deep, category:unspecified-high, or category:unspecified-low. Optional codeReview.by accepts lazycodex-code-reviewer or main-session.",
 				]
@@ -118,7 +124,7 @@ export async function checkpointTemplate(
 		...(hasAttempt ? [] : ["This plan is evidence-layout v1; artifacts go under .omo/evidence/."]),
 	].join(" ");
 	return {
-		qualityGateTemplate: gateTemplate(resolveToolkitSurface(), attemptDir),
+		qualityGateTemplate: gateTemplate(surface, attemptDir),
 		codexGoalTemplate: {
 			goal: { objective: plan.codexObjective ?? "<replace:codex objective>", status: "complete" },
 		},

package/packages/omo-codex/plugin/components/ulw-loop/src/checkpoint.ts

@@ -17,7 +17,7 @@ import {
 	sameBlockerOccurrences,
 	validateQualityGate,
 } from "./quality-gate.js";
-import { resolveToolkitSurface } from "./surface.js";
+import { resolveToolkitSurface, type UlwLoopToolkitSurface } from "./surface.js";
 import type {
 	UlwLoopAggregateCompletion,
 	UlwLoopItem,
@@ -35,6 +35,9 @@ export interface CheckpointUlwLoopArgs {
 	readonly codexGoalJson?: string;
 	readonly qualityGateJson?: string;
 }
+export interface CheckpointUlwLoopDependencies {
+	readonly surface?: UlwLoopToolkitSurface;
+}
 export interface CheckpointUlwLoopResult {
 	readonly plan: UlwLoopPlan;
 	readonly goal: UlwLoopItem;
@@ -151,6 +154,7 @@ export async function checkpointUlwLoop(
 	repoRoot: string,
 	args: CheckpointUlwLoopArgs,
 	scope?: UlwLoopScope,
+	dependencies?: CheckpointUlwLoopDependencies,
 ): Promise<CheckpointUlwLoopResult> {
 	return withUlwLoopMutationLock(repoRoot, scope, async () => {
 		const plan = await readUlwLoopPlan(repoRoot, scope);
@@ -198,7 +202,7 @@ export async function checkpointUlwLoop(
 					qualityGate = validateQualityGate(await readJsonInput(args.qualityGateJson, repoRoot), {
 						repoRoot,
 						fs: QUALITY_GATE_FS,
-						reviewerSurface: resolveToolkitSurface(),
+						reviewerSurface: dependencies?.surface ?? resolveToolkitSurface(),
 						...(plan.evidenceLayoutVersion === 2
 							? { currentAttemptDir: ulwLoopAttemptEvidenceDir(goal.id, goal.attempt, scope) }
 							: {}),