oh-my-opencode 5.0.0-beta.6 → 5.0.0-beta.62

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

@@ -2,22 +2,19 @@
 import { existsSync, statSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
-import { buildTaskScopedAggregateReconciliationHint, canReconcileActiveFinalTaskScopedAggregateSnapshot, canReconcileCompletedTaskScopedAggregateSnapshot, } from "./checkpoint-reconciliation.js";
-import { formatCodexGoalReconciliation, readCodexGoalSnapshotInput, reconcileCodexGoalSnapshot, } from "./codex-goal-snapshot.js";
+import { combineCheckpointValidationErrors, validateCheckpointCodexGoal, } from "./checkpoint-codex-validation.js";
 import { requireAllCriteriaPass, requireAllPlanCriteriaPass, requireEssentialCriteriaPass } from "./evidence.js";
-import { codexGoalMode, compatibleCodexObjectives, expectedCodexObjective, isFinalRunCompletionCandidate, } from "./goal-status.js";
+import { codexGoalMode, isFinalRunCompletionCandidate } from "./goal-status.js";
 import { ulwLoopAttemptEvidenceDir } from "./paths.js";
 import { appendLedger, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
 import { classifyExternalAuthorizationBlocker, clearGoalBlockerFields, sameBlockerOccurrences, validateQualityGate, } from "./quality-gate.js";
+import { resolveToolkitSurface } from "./surface.js";
 import { iso, UlwLoopError } from "./types.js";
 import { batchClosedBy, requireAllValidationBatchesClosed, requireBatchFinalReady, requireBatchGate } from "./validation-batch.js";
 const QUALITY_GATE_FS = { existsSync, statSync };
 function ulwLoopFail(message, code) {
     throw new UlwLoopError(message, code);
 }
-function normalizeObjective(value) {
-    return value.replace(/\s+/g, " ").trim();
-}
 function nonEmptyEvidence(value) {
     const trimmed = value.trim();
     return trimmed || ulwLoopFail("Evidence must be a non-empty string.", "ulw_loop_evidence_required");
@@ -82,13 +79,15 @@ function ledgerKind(status, goal, aggregateCompletion) {
     return status === "blocked" ? "goal_blocked" : "goal_failed";
 }
 function buildLedger(now, args, goal, qualityGate, codexGoal, aggregateCompletion) {
-    const watch = qualityGate?.codeReview.codeQualityStatus === "WATCH";
+    const watch = qualityGate?.surface === "lazycodex" && qualityGate.codeReview?.codeQualityStatus === "WATCH";
     const entry = {
         at: now,
         kind: ledgerKind(args.status, goal, aggregateCompletion),
         goalId: goal.id,
         status: goal.status,
-        evidence: watch ? `${args.evidence} | codeQuality=WATCH: ${qualityGate.codeReview.evidence}` : args.evidence,
+        evidence: watch && qualityGate.surface === "lazycodex"
+            ? `${args.evidence} | codeQuality=WATCH: ${qualityGate.codeReview?.evidence ?? ""}`
+            : args.evidence,
     };
     if (codexGoal !== undefined)
         entry.codexGoal = codexGoal;
@@ -102,7 +101,7 @@ function buildLedger(now, args, goal, qualityGate, codexGoal, aggregateCompletio
         entry.requiredExternalDecision = goal.requiredExternalDecision;
     return entry;
 }
-export async function checkpointUlwLoop(repoRoot, args, scope) {
+export async function checkpointUlwLoop(repoRoot, args, scope, dependencies) {
     return withUlwLoopMutationLock(repoRoot, scope, async () => {
         const plan = await readUlwLoopPlan(repoRoot, scope);
         const goal = findGoal(plan, args.goalId);
@@ -111,6 +110,8 @@ export async function checkpointUlwLoop(repoRoot, args, scope) {
         let aggregateCompletion;
         let qualityGate;
         let codexGoal;
+        let nextActions = [];
+        let warnings = [];
         if (args.status === "complete") {
             const aggregate = codexGoalMode(plan) === "aggregate";
             const final = isFinalRunCompletionCandidate(plan, goal);
@@ -124,29 +125,24 @@ export async function checkpointUlwLoop(repoRoot, args, scope) {
                 requireEssentialCriteriaPass(goal);
             else
                 requireAllCriteriaPass(goal);
-            const snapshot = await readCodexGoalSnapshotInput(args.codexGoalJson, repoRoot);
-            const reconciliation = reconcileCodexGoalSnapshot(snapshot, {
-                expectedObjective: expectedCodexObjective(plan, goal),
-                ...(aggregate ? { acceptedObjectives: compatibleCodexObjectives(plan) } : {}),
-                allowedStatuses: aggregate ? (final ? ["complete"] : ["active"]) : ["complete"],
-                requireSnapshot: true,
-                requireComplete: !aggregate || final,
-            });
-            codexGoal = reconciliation.snapshot.raw;
-            if (!reconciliation.ok) {
-                const objective = snapshot?.objective;
-                const mismatchedTaskObjective = snapshot?.available === true &&
-                    objective !== undefined &&
-                    normalizeObjective(objective) !== normalizeObjective(expectedCodexObjective(plan, goal));
-                const completedTaskScoped = mismatchedTaskObjective &&
-                    snapshot.status === "complete" &&
-                    (await canReconcileCompletedTaskScopedAggregateSnapshot(repoRoot, plan, goal, objective, evidence, scope));
-                const activeFinalTaskScoped = mismatchedTaskObjective &&
-                    snapshot.status === "active" &&
-                    (await canReconcileActiveFinalTaskScopedAggregateSnapshot(repoRoot, plan, goal, objective, evidence, scope));
-                const taskScoped = completedTaskScoped || activeFinalTaskScoped;
-                if (!taskScoped)
-                    throw new UlwLoopError(`${formatCodexGoalReconciliation(reconciliation)}${aggregate && snapshot?.status === "complete" && objective !== undefined ? buildTaskScopedAggregateReconciliationHint(goal, final) : ""}`, "ulw_loop_codex_snapshot_mismatch");
+            let codexValidationError;
+            try {
+                const validation = await validateCheckpointCodexGoal({
+                    repoRoot,
+                    plan,
+                    goal,
+                    raw: args.codexGoalJson,
+                    evidence,
+                    ...(scope === undefined ? {} : { scope }),
+                });
+                codexGoal = validation.raw;
+                nextActions = validation.nextActions;
+                warnings = validation.warnings;
+            }
+            catch (error) {
+                if (!(error instanceof UlwLoopError))
+                    throw error;
+                codexValidationError = error;
             }
             if (closesBatch)
                 requireBatchFinalReady(plan, goal);
@@ -155,15 +151,25 @@ export async function checkpointUlwLoop(repoRoot, args, scope) {
             if (final)
                 aggregateCompletion = makeAggregateCompletion(now, evidence, codexGoal);
             if (final || aggregateCompletion !== undefined || closesBatch) {
-                qualityGate = validateQualityGate(await readJsonInput(args.qualityGateJson, repoRoot), {
-                    repoRoot,
-                    fs: QUALITY_GATE_FS,
-                    ...(plan.evidenceLayoutVersion === 2
-                        ? { currentAttemptDir: ulwLoopAttemptEvidenceDir(goal.id, goal.attempt, scope) }
-                        : {}),
-                });
-                requireBatchGate(plan, goal, qualityGate);
+                try {
+                    qualityGate = validateQualityGate(await readJsonInput(args.qualityGateJson, repoRoot), {
+                        repoRoot,
+                        fs: QUALITY_GATE_FS,
+                        reviewerSurface: dependencies?.surface ?? resolveToolkitSurface(),
+                        ...(plan.evidenceLayoutVersion === 2
+                            ? { currentAttemptDir: ulwLoopAttemptEvidenceDir(goal.id, goal.attempt, scope) }
+                            : {}),
+                    });
+                    requireBatchGate(plan, goal, qualityGate);
+                }
+                catch (error) {
+                    if (!(error instanceof UlwLoopError) || codexValidationError === undefined)
+                        throw error;
+                    throw combineCheckpointValidationErrors(codexValidationError, error);
+                }
             }
+            if (codexValidationError !== undefined)
+                throw codexValidationError;
             goal.status = "complete";
             goal.completedAt = now;
             goal.evidence = evidence;
@@ -178,6 +184,8 @@ export async function checkpointUlwLoop(repoRoot, args, scope) {
         goal.updatedAt = now;
         if (aggregateCompletion !== undefined)
             plan.aggregateCompletion = aggregateCompletion;
+        if (aggregateCompletion !== undefined)
+            nextActions = [...nextActions, 'aggregate complete — now update_goal({status:"complete"})'];
         plan.updatedAt = now;
         await writePlan(repoRoot, plan, scope);
         const ledgerEntry = buildLedger(now, args, goal, qualityGate, codexGoal, aggregateCompletion);
@@ -186,7 +194,7 @@ export async function checkpointUlwLoop(repoRoot, args, scope) {
         if (closedBatch !== undefined)
             await appendLedger(repoRoot, { at: now, kind: "batch_closed", goalId: goal.id, message: closedBatch.batchId }, scope);
         return aggregateCompletion === undefined
-            ? { plan, goal, ledgerEntry }
-            : { plan, goal, ledgerEntry, aggregateCompletion };
+            ? { plan, goal, ledgerEntry, nextActions, warnings }
+            : { plan, goal, ledgerEntry, aggregateCompletion, nextActions, warnings };
     });
 }

package/packages/omo-codex/plugin/components/ulw-loop/dist/cli-arg-parser.js

@@ -66,14 +66,14 @@ export async function readJsonInput(value) {
 export async function parseCodexGoalJson(value) {
     if (value === undefined)
         return undefined;
-    const raw = looksLikeJson(value) ? value : await readFile(value, "utf8");
     try {
+        const raw = looksLikeJson(value) ? value : await readFile(value, "utf8");
         JSON.parse(raw);
         return raw;
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "unknown error";
-        throw new UlwLoopError(`Invalid --codex-goal-json: ${message}`, "ULW_LOOP_CODEX_GOAL_JSON_INVALID", { cause: error });
+        throw new UlwLoopError(`Invalid --codex-goal-json: ${looksLikeJson(value) ? message : "neither valid JSON nor a readable path"}`, "ULW_LOOP_CODEX_GOAL_JSON_INVALID", { cause: error });
     }
 }
 function required(argv, flag, code) {

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

@@ -1,8 +1,10 @@
 import { checkpoint } from "./checkpoint-continuation.js";
 import { hasFlag, readValue } from "./cli-arg-parser.js";
-import { printJsonError, ULW_LOOP_HELP } from "./cli-output.js";
+import { printJsonError, subcommandHelp, ULW_LOOP_HELP } from "./cli-output.js";
 import { addGoal, captureEvidence, completeGoals, createGoals, criteria, reviewBlockers, status, steer, } from "./cli-subcommands.js";
 import { resolveUlwLoopSessionIdFromEnv } from "./paths.js";
+import { listUlwLoopSessionIds } from "./plan-io.js";
+import { sessionIdRequiredMessage, sessionScopeRequiredMessage } from "./plan-missing-recovery.js";
 import { UlwLoopError } from "./types.js";
 export const ULW_LOOP_SUBCOMMANDS = [
     "help",
@@ -26,7 +28,6 @@ export async function ulwLoopCommand(argv) {
     const repoRoot = process.cwd();
     const json = hasFlag(rest, "--json");
     try {
-        const scope = commandScope(rest);
         if (!isUlwLoopSubcommand(command)) {
             if (json) {
                 printJsonError(new UlwLoopError(`Unknown ulw-loop subcommand: ${command}.`, "ULW_LOOP_SUBCOMMAND_UNKNOWN", {
@@ -37,10 +38,16 @@ export async function ulwLoopCommand(argv) {
             process.stdout.write(`${ULW_LOOP_HELP}\n`);
             return 1;
         }
+        if (command !== "help" && (hasFlag(rest, "--help") || hasFlag(rest, "-h"))) {
+            process.stdout.write(`${subcommandHelp(command)}\n`);
+            return 0;
+        }
+        if (command === "help") {
+            process.stdout.write(`${ULW_LOOP_HELP}\n`);
+            return 0;
+        }
+        const scope = commandScope(repoRoot, rest);
         switch (command) {
-            case "help":
-                process.stdout.write(`${ULW_LOOP_HELP}\n`);
-                return 0;
             case "create-goals":
                 return await createGoals(repoRoot, rest, json, scope);
             case "status":
@@ -84,16 +91,22 @@ const SESSION_ID_FLAG = "--session-id";
 function sessionIdFlagPresent(argv) {
     return hasFlag(argv, SESSION_ID_FLAG) || argv.some((arg) => arg.startsWith(`${SESSION_ID_FLAG}=`));
 }
-function commandScope(argv) {
+// Every state subcommand runs against exactly one session directory. Without a flag or
+// a session env there is no owner to resolve, so the command refuses instead of
+// falling back to the repo-global root that every session in the cwd would share.
+function commandScope(repoRoot, argv) {
     if (sessionIdFlagPresent(argv)) {
         const sessionId = readValue(argv, SESSION_ID_FLAG)?.trim();
         if (!sessionId) {
-            throw new UlwLoopError(`${SESSION_ID_FLAG} requires a non-empty value.`, "ULW_LOOP_SESSION_ID_REQUIRED", {
+            throw new UlwLoopError(sessionIdRequiredMessage(SESSION_ID_FLAG), "ULW_LOOP_SESSION_ID_REQUIRED", {
                 details: { flag: SESSION_ID_FLAG },
             });
         }
         return { sessionId };
     }
     const sessionId = resolveUlwLoopSessionIdFromEnv();
-    return sessionId === null ? undefined : { sessionId };
+    if (sessionId !== null)
+        return { sessionId };
+    const existingSessionIds = listUlwLoopSessionIds(repoRoot);
+    throw new UlwLoopError(sessionScopeRequiredMessage(SESSION_ID_FLAG, existingSessionIds), "ULW_LOOP_SESSION_SCOPE_REQUIRED", { details: { flag: SESSION_ID_FLAG, existingSessionIds } });
 }

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

@@ -1,5 +1,6 @@
 import type { UlwLoopCodexGoalMode, UlwLoopPlan } from "./types.js";
-export declare const ULW_LOOP_HELP = "Usage:\n  omo-agent-toolkit ulw-loop create-goals --brief \"...\" [--brief-file <path>] [--from-stdin] [--codex-goal-mode aggregate|per_story] [--validation-batch-json <json-or-path>] [--force] [--json]\n  omo-agent-toolkit ulw-loop status [--json]\n  omo-agent-toolkit ulw-loop complete-goals [--retry-failed] [--json]\n  omo-agent-toolkit ulw-loop criteria --goal-id <id> [--json]\n  omo-agent-toolkit ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status pass|fail|blocked --evidence \"...\" [--notes \"...\"] [--json]\n  omo-agent-toolkit ulw-loop checkpoint --goal-id <id> --status complete|failed|blocked --evidence \"...\" --codex-goal-json <...> [--quality-gate-json <...>] [--no-advance] [--json]\n  omo-agent-toolkit ulw-loop steer --kind <kind> ... --evidence \"...\" --rationale \"...\" [--proposals-json <json-or-path>] [--json]\n  omo-agent-toolkit ulw-loop add-goal --title \"...\" --objective \"...\" [--json]\n  omo-agent-toolkit ulw-loop record-review-blockers --goal-id <id> --title \"...\" --objective \"...\" --evidence \"...\" --codex-goal-json <...> [--json]\n\nAll subcommands accept [--session-id <id>] to isolate state under .omo/ulw-loop/<id>/; without it, Codex session env is used when present.";
+export declare const ULW_LOOP_HELP = "Usage:\n  omo-agent-toolkit hook user-prompt-submit [--with-ultrawork]  (Codex UserPromptSubmit hook)\n  omo-agent-toolkit help | --help | -h                          (this message)\n  omo-agent-toolkit ulw-loop help\n  omo-agent-toolkit ulw-loop create-goals --brief \"...\" [--brief-file <path>] [--from-stdin] [--codex-goal-mode aggregate|per_story] [--validation-batch-json <json-or-path>] [--force] [--json]\n  omo-agent-toolkit ulw-loop status [--json]\n  omo-agent-toolkit ulw-loop complete-goals [--retry-failed] [--json]\n  omo-agent-toolkit ulw-loop criteria --goal-id <id> [--json]\n  omo-agent-toolkit ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status pass|fail|blocked --evidence \"...\" [--notes \"...\"] [--json]\n  omo-agent-toolkit ulw-loop checkpoint --print-template [--goal-id <id>] [--json]\n  omo-agent-toolkit ulw-loop checkpoint --goal-id <id> --status complete|failed|blocked --evidence \"...\" --codex-goal-json <...> [--quality-gate-json <...>] [--no-advance] [--json]\n  omo-agent-toolkit ulw-loop steer --kind <kind> ... --evidence \"...\" --rationale \"...\" [--proposals-json <json-or-path>] [--json]\n  omo-agent-toolkit ulw-loop add-goal --title \"...\" --objective \"...\" [--json]\n  omo-agent-toolkit ulw-loop record-review-blockers --goal-id <id> --title \"...\" --objective \"...\" --evidence \"...\" --codex-goal-json <...> [--json]\n\nEvery state subcommand needs a session scope: [--session-id <id>] or the session env (OMO_ULW_LOOP_SESSION_ID / CODEX_SESSION_ID / CODEX_THREAD_ID / PI_SESSION_ID); state lives under .omo/ulw-loop/<id>/ and the unscoped root is never used implicitly. status --json exposes the currentAttemptDir; put all quality-gate artifacts under it.\nEvery subcommand accepts --help | -h to print its own usage line.";
+export declare function subcommandHelp(subcommand: string): string;
 export declare function printJson(value: unknown): void;
 export declare function printJsonError(error: unknown): void;
 export declare function printStatus(plan: UlwLoopPlan): void;

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

@@ -1,16 +1,27 @@
 import { UlwLoopError } from "./types.js";
 export const ULW_LOOP_HELP = `Usage:
+  omo-agent-toolkit hook user-prompt-submit [--with-ultrawork]  (Codex UserPromptSubmit hook)
+  omo-agent-toolkit help | --help | -h                          (this message)
+  omo-agent-toolkit ulw-loop help
   omo-agent-toolkit ulw-loop create-goals --brief "..." [--brief-file <path>] [--from-stdin] [--codex-goal-mode aggregate|per_story] [--validation-batch-json <json-or-path>] [--force] [--json]
   omo-agent-toolkit ulw-loop status [--json]
   omo-agent-toolkit ulw-loop complete-goals [--retry-failed] [--json]
   omo-agent-toolkit ulw-loop criteria --goal-id <id> [--json]
   omo-agent-toolkit ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status pass|fail|blocked --evidence "..." [--notes "..."] [--json]
+  omo-agent-toolkit ulw-loop checkpoint --print-template [--goal-id <id>] [--json]
   omo-agent-toolkit ulw-loop checkpoint --goal-id <id> --status complete|failed|blocked --evidence "..." --codex-goal-json <...> [--quality-gate-json <...>] [--no-advance] [--json]
   omo-agent-toolkit ulw-loop steer --kind <kind> ... --evidence "..." --rationale "..." [--proposals-json <json-or-path>] [--json]
   omo-agent-toolkit ulw-loop add-goal --title "..." --objective "..." [--json]
   omo-agent-toolkit ulw-loop record-review-blockers --goal-id <id> --title "..." --objective "..." --evidence "..." --codex-goal-json <...> [--json]
 
-All subcommands accept [--session-id <id>] to isolate state under .omo/ulw-loop/<id>/; without it, Codex session env is used when present.`;
+Every state subcommand needs a session scope: [--session-id <id>] or the session env (OMO_ULW_LOOP_SESSION_ID / CODEX_SESSION_ID / CODEX_THREAD_ID / PI_SESSION_ID); state lives under .omo/ulw-loop/<id>/ and the unscoped root is never used implicitly. status --json exposes the currentAttemptDir; put all quality-gate artifacts under it.
+Every subcommand accepts --help | -h to print its own usage line.`;
+export function subcommandHelp(subcommand) {
+    const lines = ULW_LOOP_HELP.split("\n").filter((line) => line.trimStart().startsWith(`omo-agent-toolkit ulw-loop ${subcommand}`));
+    if (lines.length === 0)
+        return ULW_LOOP_HELP;
+    return ["Usage:", ...lines].join("\n");
+}
 export function printJson(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }

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

@@ -1,4 +1,4 @@
-import { type UlwLoopScope } from "./paths.js";
+import type { UlwLoopScope } from "./paths.js";
 export declare function createGoals(repoRoot: string, argv: readonly string[], json: boolean, scope?: UlwLoopScope): Promise<number>;
 export declare function status(repoRoot: string, json: boolean, scope?: UlwLoopScope): Promise<number>;
 export declare function completeGoals(repoRoot: string, argv: readonly string[], json: boolean, scope?: UlwLoopScope): Promise<number>;

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

@@ -3,14 +3,11 @@ import { hasFlag, parseCodexGoalJson, parseRecordEvidenceArgs, positionalText, r
 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 { 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 { steerUlwLoop } from "./steering.js";
+import { summarizeUlwLoopPlan } from "./plan-crud.js";
+import { createAgentToolkit } from "./sdk.js";
 import { steerUlwLoopBatch } from "./steering-batch.js";
+import { resolveToolkitSurface } from "./surface.js";
 import { UlwLoopError } from "./types.js";
 export async function createGoals(repoRoot, argv, json, scope) {
     const briefFile = readValue(argv, "--brief-file");
@@ -22,12 +19,12 @@ export async function createGoals(repoRoot, argv, json, scope) {
         throw new UlwLoopError("Missing brief text. Pass --brief, --brief-file, --from-stdin, or positional text.", "ULW_LOOP_BRIEF_REQUIRED");
     }
     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 {
@@ -36,25 +33,15 @@ export async function createGoals(repoRoot, argv, json, scope) {
     return 0;
 }
 export async function status(repoRoot, json, scope) {
-    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 }),
-        });
-    }
+    const status = unwrap(await toolkitFor(repoRoot, scope).status());
+    if (json)
+        printJson({ ok: true, ...status });
     else
-        printStatus(plan);
+        printStatus(status.plan);
     return 0;
 }
 export async function completeGoals(repoRoot, argv, json, scope) {
-    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) {
@@ -82,7 +69,7 @@ export async function steer(repoRoot, argv, json, scope) {
     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;
     }
@@ -91,7 +78,10 @@ export async function steer(repoRoot, argv, json, scope) {
     return result.accepted ? 0 : 1;
 }
 export async function addGoal(repoRoot, argv, json, scope) {
-    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 {
@@ -102,16 +92,16 @@ export async function addGoal(repoRoot, argv, json, scope) {
 }
 export async function criteria(repoRoot, argv, json, scope) {
     const goalId = required(argv, "--goal-id");
-    const goal = findGoal(await readUlwLoopPlan(repoRoot, scope), goalId);
+    const result = unwrap(await toolkitFor(repoRoot, scope).criteria({ goalId }));
     if (json)
-        printJson({ ok: true, goalId: goal.id, criteria: goal.successCriteria });
+        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;
 }
 export async function captureEvidence(repoRoot, argv, json, scope) {
-    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 {
@@ -124,13 +114,13 @@ export async function reviewBlockers(repoRoot, argv, json, scope) {
     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({
             ok: true,
@@ -138,6 +128,8 @@ export async function reviewBlockers(repoRoot, argv, json, scope) {
             blockedGoal: result.blockedGoal,
             goal: result.newGoal,
             ledgerEntries: result.ledgerEntries,
+            nextActions: result.nextActions,
+            warnings: result.warnings,
             summary: summarizeUlwLoopPlan(result.plan),
         });
     }
@@ -146,6 +138,23 @@ export async function reviewBlockers(repoRoot, argv, json, scope) {
     }
     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, scope) {
+    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(response) {
+    if (response.ok)
+        return response.result;
+    throw new UlwLoopError(response.error.message, response.error.code);
+}
 function formatCriterionForCli(criterion) {
     const marker = isEssentialCriterion(criterion) ? "essential" : "non-essential";
     return `- ${criterion.id} [${criterion.status}] [${marker}] (${criterion.userModel}) ${criterion.scenario} evidence: ${criterion.capturedEvidence ?? "pending"}`;
@@ -156,9 +165,3 @@ function required(argv, flag) {
         return value;
     throw new UlwLoopError(`Missing ${flag}.`, "ULW_LOOP_ARGUMENT_MISSING", { details: { flag } });
 }
-function findGoal(plan, goalId) {
-    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 } });
-}