oh-my-opencode 5.0.0-beta.56 → 5.0.0-beta.60

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

@@ -0,0 +1,125 @@
+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";
+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);
+}
+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 })
+            : checkpointUlwLoop(context.cwd, args, scope, { surface: context.surface })),
+        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/hooks/hooks.json

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook user-prompt-submit --with-ultrawork",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.56) Checking Ulw-Loop Steering"
+						"statusMessage": "(OmO 5.0.0-beta.60) Checking Ulw-Loop Steering"
 					}
 				]
 			}
@@ -20,7 +20,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook post-tool-use-spawn",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.56) Recording Spawn Admission"
+						"statusMessage": "(OmO 5.0.0-beta.60) Recording Spawn Admission"
 					}
 				]
 			}
@@ -33,7 +33,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.56) Enforcing Unlimited Ulw-Loop Budget"
+						"statusMessage": "(OmO 5.0.0-beta.60) Enforcing Unlimited Ulw-Loop Budget"
 					}
 				]
 			},
@@ -44,7 +44,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use-spawn",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.56) Guarding Ulw-Loop Spawns"
+						"statusMessage": "(OmO 5.0.0-beta.60) 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.56) Checking Ulw-Loop Resume"
+						"statusMessage": "(OmO 5.0.0-beta.60) 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.56",
+	"version": "5.0.0-beta.60",
 	"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) }
 							: {}),

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

@@ -11,15 +11,12 @@ import {
 import { blockedDecisionHandoff, normalizeCodexGoalMode, printJson, printStatus } from "./cli-output.js";
 import { parseSteeringProposals, printSteerBatchResult, printSteerResult } from "./cli-steering.js";
 import { buildCodexGoalInstruction } from "./codex-goal-instruction.js";
-import { recordEvidence } from "./evidence.js";
 import { isEssentialCriterion } from "./goal-status.js";
-import { type UlwLoopScope, 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 { statusNextActions } from "./status-next-actions.js";
-import { steerUlwLoop } from "./steering.js";
+import type { UlwLoopScope } from "./paths.js";
+import { summarizeUlwLoopPlan } from "./plan-crud.js";
+import { type AgentToolkit, createAgentToolkit } from "./sdk.js";
 import { steerUlwLoopBatch } from "./steering-batch.js";
+import { resolveToolkitSurface } from "./surface.js";
 import type { UlwLoopItem } from "./types.js";
 import { UlwLoopError } from "./types.js";
 
@@ -42,15 +39,13 @@ export async function createGoals(
 		);
 	}
 	const validationBatchesJson = readValue(argv, "--validation-batch-json");
-	const plan = await createUlwLoopPlan(
-		repoRoot,
-		{
+	const plan = unwrap(
+		await toolkitFor(repoRoot, scope).createGoals({
 			brief,
 			codexGoalMode: normalizeCodexGoalMode(readValue(argv, "--codex-goal-mode")),
 			force: hasFlag(argv, "--force"),
 			...(validationBatchesJson === undefined ? {} : { validationBatchesJson }),
-		},
-		scope,
+		}),
 	);
 	if (json) printJson({ ok: true, plan, summary: summarizeUlwLoopPlan(plan) });
 	else {
@@ -62,21 +57,9 @@ export async function createGoals(
 }
 
 export async function status(repoRoot: string, json: boolean, scope?: UlwLoopScope): Promise<number> {
-	const plan = await readUlwLoopPlan(repoRoot, scope);
-	if (json) {
-		const active = plan.goals.find((goal) => goal.id === plan.activeGoalId);
-		const currentAttemptDir =
-			plan.evidenceLayoutVersion === 2 && active
-				? ulwLoopAttemptEvidenceDir(active.id, active.attempt, scope)
-				: undefined;
-		printJson({
-			ok: true,
-			plan,
-			summary: summarizeUlwLoopPlan(plan),
-			...(currentAttemptDir === undefined ? {} : { currentAttemptDir }),
-			nextActions: statusNextActions(plan),
-		});
-	} else printStatus(plan);
+	const status = unwrap(await toolkitFor(repoRoot, scope).status());
+	if (json) printJson({ ok: true, ...status });
+	else printStatus(status.plan);
 	return 0;
 }
 
@@ -86,7 +69,9 @@ export async function completeGoals(
 	json: boolean,
 	scope?: UlwLoopScope,
 ): Promise<number> {
-	const result = await startNextUlwLoop(repoRoot, { retryFailed: hasFlag(argv, "--retry-failed") }, scope);
+	const result = unwrap(
+		await toolkitFor(repoRoot, scope).completeGoals({ retryFailed: hasFlag(argv, "--retry-failed") }),
+	);
 	if ("done" in result) {
 		const handoff = blockedDecisionHandoff(result.plan);
 		if (json) {
@@ -116,7 +101,7 @@ export async function steer(
 	const proposals = await parseSteeringProposals(argv);
 	const single = proposals[0];
 	if (single !== undefined && proposals.length === 1 && readValue(argv, "--proposals-json") === undefined) {
-		const result = await steerUlwLoop(repoRoot, single, scope);
+		const result = unwrap(await toolkitFor(repoRoot, scope).steer(single));
 		printSteerResult(result, json);
 		return result.accepted ? 0 : 1;
 	}
@@ -131,10 +116,11 @@ export async function addGoal(
 	json: boolean,
 	scope?: UlwLoopScope,
 ): Promise<number> {
-	const result = await addUlwLoopGoal(
-		repoRoot,
-		{ title: required(argv, "--title"), objective: required(argv, "--objective") },
-		scope,
+	const result = unwrap(
+		await toolkitFor(repoRoot, scope).addGoal({
+			title: required(argv, "--title"),
+			objective: required(argv, "--objective"),
+		}),
 	);
 	if (json) printJson({ ok: true, plan: result.plan, goal: result.goal, summary: summarizeUlwLoopPlan(result.plan) });
 	else {
@@ -151,10 +137,12 @@ export async function criteria(
 	scope?: UlwLoopScope,
 ): Promise<number> {
 	const goalId = required(argv, "--goal-id");
-	const goal = findGoal(await readUlwLoopPlan(repoRoot, scope), goalId);
-	if (json) printJson({ ok: true, goalId: goal.id, criteria: goal.successCriteria });
+	const result = unwrap(await toolkitFor(repoRoot, scope).criteria({ goalId }));
+	if (json) printJson({ ok: true, goalId: result.goalId, criteria: result.criteria });
 	else {
-		process.stdout.write(`criteria for ${goal.id}:\n${goal.successCriteria.map(formatCriterionForCli).join("\n")}\n`);
+		process.stdout.write(
+			`criteria for ${result.goalId}:\n${result.criteria.map(formatCriterionForCli).join("\n")}\n`,
+		);
 	}
 	return 0;
 }
@@ -165,7 +153,7 @@ export async function captureEvidence(
 	json: boolean,
 	scope?: UlwLoopScope,
 ): Promise<number> {
-	const result = await recordEvidence(repoRoot, parseRecordEvidenceArgs(argv), scope);
+	const result = unwrap(await toolkitFor(repoRoot, scope).recordEvidence(parseRecordEvidenceArgs(argv)));
 	if (json) printJson({ ok: true, ...result, summary: summarizeUlwLoopPlan(result.plan) });
 	else {
 		process.stdout.write(
@@ -185,16 +173,14 @@ export async function reviewBlockers(
 	if (codexGoalJson === undefined) {
 		throw new UlwLoopError("Missing --codex-goal-json.", "ULW_LOOP_CODEX_GOAL_JSON_REQUIRED");
 	}
-	const result = await recordFinalReviewBlockers(
-		repoRoot,
-		{
+	const result = unwrap(
+		await toolkitFor(repoRoot, scope).recordReviewBlockers({
 			goalId: required(argv, "--goal-id"),
 			title: required(argv, "--title"),
 			objective: required(argv, "--objective"),
 			evidence: required(argv, "--evidence"),
 			codexGoalJson,
-		},
-		scope,
+		}),
 	);
 	if (json) {
 		printJson({
@@ -215,6 +201,28 @@ export async function reviewBlockers(
 	return 0;
 }
 
+// Every subcommand runs through the SDK so state logic lives in one place; the CLI keeps only argv
+// parsing and the legacy output shapes. A failed envelope is rethrown as the typed error the CLI's
+// JSON error path already prints.
+function toolkitFor(repoRoot: string, scope?: UlwLoopScope): AgentToolkit {
+	const sessionId = scope?.sessionId?.trim();
+	if (sessionId === undefined || sessionId.length === 0) {
+		throw new UlwLoopError("Missing --session-id.", "ULW_LOOP_SESSION_ID_REQUIRED", {
+			details: { flag: "--session-id" },
+		});
+	}
+	return createAgentToolkit({ cwd: repoRoot, sessionId, surface: resolveToolkitSurface() });
+}
+
+function unwrap<Result>(
+	response:
+		| { readonly ok: true; readonly result: Result }
+		| { readonly ok: false; readonly error: { readonly code: string; readonly message: string } },
+): Result {
+	if (response.ok) return response.result;
+	throw new UlwLoopError(response.error.message, response.error.code);
+}
+
 function formatCriterionForCli(criterion: UlwLoopItem["successCriteria"][number]): string {
 	const marker = isEssentialCriterion(criterion) ? "essential" : "non-essential";
 	return `- ${criterion.id} [${criterion.status}] [${marker}] (${criterion.userModel}) ${criterion.scenario} evidence: ${criterion.capturedEvidence ?? "pending"}`;
@@ -225,9 +233,3 @@ function required(argv: readonly string[], flag: string): string {
 	if (value) return value;
 	throw new UlwLoopError(`Missing ${flag}.`, "ULW_LOOP_ARGUMENT_MISSING", { details: { flag } });
 }
-
-function findGoal(plan: { readonly goals: readonly UlwLoopItem[] }, goalId: string): UlwLoopItem {
-	const goal = plan.goals.find((candidate) => candidate.id === goalId);
-	if (goal !== undefined) return goal;
-	throw new UlwLoopError(`Unknown ulw-loop id: ${goalId}.`, "ULW_LOOP_GOAL_NOT_FOUND", { details: { goalId } });
-}