oh-my-opencode 4.8.1 → 4.9.1

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

@@ -0,0 +1,13 @@
+export class UlwLoopError extends Error {
+    constructor(message, code, opts) {
+        super(message, opts?.cause === undefined ? undefined : { cause: opts.cause });
+        this.name = "UlwLoopError";
+        this.code = code;
+        if (opts?.details !== undefined) {
+            this.details = opts.details;
+        }
+    }
+}
+export function iso() {
+    return new Date().toISOString();
+}

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

@@ -0,0 +1,63 @@
+import type { UlwLoopSteeringMutationKind, UlwLoopSteeringSource } from "./constants.js";
+import type { UlwLoopPlan } from "./domain-types.js";
+export interface UlwLoopSteeringInvariantResult {
+    accepted: boolean;
+    structuralInvariantAccepted: boolean;
+    evidenceBackedNecessity: boolean;
+    noEasierCompletion: boolean;
+    rejectedReasons: string[];
+    reasons?: string[];
+}
+export interface UlwLoopSteeringChildGoal {
+    title: string;
+    objective: string;
+}
+export interface UlwLoopSteeringAfterPayload {
+    title?: string;
+    objective?: string;
+    pendingGoalIds?: string[];
+    children?: UlwLoopSteeringChildGoal[];
+}
+export interface UlwLoopSteeringProposal {
+    kind: UlwLoopSteeringMutationKind;
+    source: UlwLoopSteeringSource;
+    targetGoalId?: string;
+    targetGoalIds?: string[];
+    criterionId?: string;
+    evidence: string;
+    rationale: string;
+    title?: string;
+    objective?: string;
+    childGoals?: UlwLoopSteeringChildGoal[];
+    revisedTitle?: string;
+    revisedObjective?: string;
+    pendingOrder?: string[];
+    blockedReason?: string;
+    after?: UlwLoopSteeringAfterPayload;
+    directiveText?: string;
+    promptSignature?: string;
+    idempotencyKey?: string;
+    now?: Date;
+}
+export interface UlwLoopSteeringAudit {
+    kind: UlwLoopSteeringMutationKind;
+    source: UlwLoopSteeringSource;
+    targetGoalIds: string[];
+    criterionId?: string;
+    before?: unknown;
+    after?: unknown;
+    evidence: string;
+    rationale: string;
+    invariant: UlwLoopSteeringInvariantResult;
+    directiveText?: string;
+    promptSignature?: string;
+    idempotencyKey?: string;
+    deduped?: boolean;
+}
+export interface SteerUlwLoopResult {
+    plan: UlwLoopPlan;
+    accepted: boolean;
+    audit: UlwLoopSteeringAudit;
+    rejectedReasons: string[];
+    deduped: boolean;
+}

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

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

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

@@ -0,0 +1,6 @@
+import type { UlwLoopScope } from "./paths.js";
+import type { SteerUlwLoopResult, UlwLoopPlan, UlwLoopSteeringAudit, UlwLoopSteeringProposal } from "./types.js";
+export declare function validateUlwLoopSteeringProposal(plan: UlwLoopPlan, proposal: unknown): UlwLoopSteeringAudit;
+export declare function applySteeringMutation(plan: UlwLoopPlan, proposal: UlwLoopSteeringProposal, audit: UlwLoopSteeringAudit): UlwLoopPlan;
+export declare function parseUlwLoopSteeringDirective(text: string): UlwLoopSteeringProposal | null;
+export declare function steerUlwLoop(repoRoot: string, proposal: UlwLoopSteeringProposal, scope?: UlwLoopScope): Promise<SteerUlwLoopResult>;

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

@@ -0,0 +1,292 @@
+// biome-ignore-all format: compact steering module must stay below the 240 pure-LOC budget
+import { isUlwLoopDone } from "./goal-status.js";
+import { seedDefaultSuccessCriteria } from "./plan-crud.js";
+import { appendLedger, readSteeringLedgerEntries, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { iso, ULW_LOOP_STEERING_MUTATION_KINDS, ULW_LOOP_SUCCESS_CRITERION_USER_MODELS } from "./types.js";
+const SOURCES = ["user_prompt_submit", "finding", "cli"];
+const PROTECTED = new Set(["aggregateCompletion", "codexObjective", "codexObjectiveAliases", "originalConstraints", "qualityGate", "status", "completedAt", "completionStatus"]);
+const isObject = (value) => typeof value === "object" && value !== null;
+const isPlain = (value) => isObject(value) && !Array.isArray(value);
+const read = (value, key) => Object.entries(value).find(([name]) => name === key)?.[1];
+const isText = (value) => typeof value === "string" && value.trim().length > 0;
+const text = (value, key) => {
+    const candidate = read(value, key);
+    return isText(candidate) ? candidate.trim() : undefined;
+};
+const isKind = (value) => typeof value === "string" && ULW_LOOP_STEERING_MUTATION_KINDS.some((kind) => kind === value);
+const isSource = (value) => typeof value === "string" && SOURCES.some((source) => source === value);
+const isModel = (value) => typeof value === "string" && ULW_LOOP_SUCCESS_CRITERION_USER_MODELS.some((model) => model === value);
+const texts = (value, key) => {
+    const candidate = read(value, key);
+    return Array.isArray(candidate) && candidate.every((item) => typeof item === "string") ? candidate : [];
+};
+function targets(proposal) {
+    const many = texts(proposal, "targetGoalIds");
+    const one = text(proposal, "targetGoalId") ?? text(proposal, "goalId");
+    return many.length > 0 ? many : one === undefined ? [] : [one];
+}
+const after = (proposal) => {
+    const candidate = read(proposal, "after");
+    return isPlain(candidate) ? candidate : undefined;
+};
+const revised = (proposal, direct, nested) => text(proposal, direct) ?? text(after(proposal) ?? proposal, nested);
+function child(value) {
+    if (!isPlain(value))
+        return null;
+    const title = text(value, "title");
+    const objective = text(value, "objective");
+    if (title === undefined || objective === undefined)
+        return null;
+    return { title, objective };
+}
+function childValues(proposal) {
+    const direct = read(proposal, "childGoals");
+    if (Array.isArray(direct) && direct.length > 0)
+        return direct;
+    const nested = after(proposal);
+    const fromAfter = nested === undefined ? undefined : read(nested, "children");
+    return Array.isArray(fromAfter) ? fromAfter : [];
+}
+const children = (proposal) => childValues(proposal).map(child).filter((item) => item !== null);
+const pendingOrder = (proposal) => {
+    const direct = texts(proposal, "pendingOrder");
+    return direct.length > 0 ? direct : texts(after(proposal) ?? proposal, "pendingGoalIds");
+};
+function hasProtected(value) {
+    if (!isObject(value))
+        return false;
+    for (const [key, childValue] of Object.entries(value))
+        if (PROTECTED.has(key) || key.toLowerCase().includes("complete") || hasProtected(childValue))
+            return true;
+    return false;
+}
+function allText(value) {
+    if (typeof value === "string")
+        return value;
+    return isObject(value) ? Object.values(value).map(allText).filter(Boolean).join("\n") : "";
+}
+function weakens(value) {
+    const valueText = allText(value).toLowerCase();
+    return /\b(skip|bypass|weaken|remove|omit|auto[-\s]?complete|mark complete|complete faster)\b/.test(valueText) && /\b(test|tests|verification|review|quality gate|complete|completion)\b/.test(valueText);
+}
+function auditFor(proposal, reasons) {
+    const object = isPlain(proposal) ? proposal : undefined;
+    const kindRaw = object === undefined ? undefined : read(object, "kind");
+    const sourceRaw = object === undefined ? undefined : read(object, "source");
+    const evidence = object === undefined ? "" : (text(object, "evidence") ?? "");
+    const rationale = object === undefined ? "" : (text(object, "rationale") ?? "");
+    const audit = { kind: isKind(kindRaw) ? kindRaw : "annotate_ledger", source: isSource(sourceRaw) ? sourceRaw : "cli", targetGoalIds: object === undefined ? [] : targets(object), evidence, rationale, invariant: { accepted: reasons.length === 0, structuralInvariantAccepted: reasons.length === 0, evidenceBackedNecessity: evidence.length > 0 && rationale.length > 0, noEasierCompletion: !weakens(proposal), rejectedReasons: reasons, reasons } };
+    if (object === undefined)
+        return audit;
+    const criterionId = text(object, "criterionId");
+    const directiveText = text(object, "directiveText");
+    const promptSignature = text(object, "promptSignature");
+    const idempotencyKey = text(object, "idempotencyKey");
+    if (criterionId !== undefined)
+        audit.criterionId = criterionId;
+    if (directiveText !== undefined)
+        audit.directiveText = directiveText;
+    if (promptSignature !== undefined)
+        audit.promptSignature = promptSignature;
+    if (idempotencyKey !== undefined)
+        audit.idempotencyKey = idempotencyKey;
+    return audit;
+}
+export function validateUlwLoopSteeringProposal(plan, proposal) {
+    const reasons = [];
+    if (!isPlain(proposal))
+        reasons.push("proposal must be an object");
+    const object = isPlain(proposal) ? proposal : {};
+    const kind = read(object, "kind");
+    if (!isKind(kind))
+        reasons.push(`invalid kind: ${String(kind)}`);
+    if (!isSource(read(object, "source")))
+        reasons.push(`invalid source: ${String(read(object, "source"))}`);
+    if (text(object, "evidence") === undefined)
+        reasons.push("missing evidence");
+    if (text(object, "rationale") === undefined)
+        reasons.push("missing rationale");
+    if (hasProtected(proposal))
+        reasons.push("protected payload");
+    if (weakens(proposal))
+        reasons.push("weakened completion");
+    if (isUlwLoopDone(plan))
+        reasons.push("plan already complete");
+    if (isKind(kind))
+        validateKind(plan, object, kind, reasons);
+    return auditFor(proposal, reasons);
+}
+function goal(plan, id) {
+    return id === undefined ? undefined : plan.goals.find((item) => item.id === id);
+}
+function validateKind(plan, proposal, kind, reasons) {
+    const target = goal(plan, targets(proposal)[0]);
+    if (kind === "add_subgoal" && (text(proposal, "title") === undefined || text(proposal, "objective") === undefined))
+        reasons.push("add_subgoal requires title/objective");
+    if ((kind === "split_subgoal" || kind === "revise_pending_wording" || kind === "mark_blocked_superseded") && target === undefined)
+        reasons.push(`${kind} requires target`);
+    if ((kind === "split_subgoal" || kind === "revise_pending_wording") && target !== undefined && target.status !== "pending")
+        reasons.push(`${kind} requires pending target`);
+    const rawChildren = childValues(proposal);
+    if (kind === "split_subgoal" && rawChildren.length === 0)
+        reasons.push("split_subgoal requires children");
+    if ((kind === "split_subgoal" || kind === "mark_blocked_superseded") && rawChildren.some((item) => child(item) === null))
+        reasons.push(`${kind} children require title/objective`);
+    if (kind === "reorder_pending")
+        validateOrder(plan, proposal, reasons);
+    if (kind === "revise_pending_wording" && revised(proposal, "revisedTitle", "title") === undefined && revised(proposal, "revisedObjective", "objective") === undefined)
+        reasons.push("revise_pending_wording requires update");
+    if (kind === "revise_criterion")
+        validateCriterion(plan, proposal, reasons);
+}
+function validateOrder(plan, proposal, reasons) {
+    const requested = pendingOrder(proposal);
+    const pending = plan.goals.filter((item) => item.status === "pending" && item.steeringStatus === undefined).map((item) => item.id);
+    if (requested.length === 0)
+        reasons.push("reorder_pending requires ids");
+    if (new Set(requested).size !== requested.length)
+        reasons.push("duplicate pending id");
+    if (requested.some((id) => !pending.includes(id)))
+        reasons.push("unknown pending id");
+}
+function validateCriterion(plan, proposal, reasons) {
+    const target = goal(plan, targets(proposal)[0]);
+    const criterionId = text(proposal, "criterionId");
+    if (target === undefined)
+        reasons.push("revise_criterion requires goalId");
+    else if (criterionId === undefined || target.successCriteria.every((item) => item.id !== criterionId))
+        reasons.push("revise_criterion requires criterionId");
+    const model = read(proposal, "userModel");
+    if (read(proposal, "scenario") === undefined && read(proposal, "expectedEvidence") === undefined && model === undefined)
+        reasons.push("revise_criterion requires update");
+    if (model !== undefined && !isModel(model))
+        reasons.push("invalid userModel");
+}
+function nextId(plan, offset) {
+    const max = plan.goals.reduce((current, item) => {
+        const digits = /^G(\d+)(?:-|$)/u.exec(item.id)?.[1];
+        return digits === undefined ? current : Math.max(current, Number(digits));
+    }, 0);
+    return `G${String(max + offset).padStart(3, "0")}`;
+}
+function makeGoal(plan, childGoal, evidence, now, offset) {
+    const id = nextId(plan, offset);
+    const digits = /^G(\d+)/u.exec(id)?.[1];
+    const goalIndex = digits === undefined ? plan.goals.length + offset - 1 : Number(digits) - 1;
+    return { id, title: childGoal.title, objective: childGoal.objective, status: "pending", successCriteria: seedDefaultSuccessCriteria(goalIndex, childGoal.objective), attempt: 0, createdAt: now, updatedAt: now, evidence };
+}
+export function applySteeringMutation(plan, proposal, audit) {
+    const next = structuredClone(plan);
+    if (!audit.invariant.accepted)
+        return next;
+    const now = proposal.now?.toISOString() ?? iso();
+    if (proposal.kind === "add_subgoal")
+        next.goals.push(makeGoal(next, { title: proposal.title ?? "", objective: proposal.objective ?? "" }, proposal.evidence, now, 1));
+    if (proposal.kind === "reorder_pending") {
+        const order = pendingOrder(proposal);
+        next.goals = [...order.map((id) => goal(next, id)).filter((item) => item !== undefined), ...next.goals.filter((item) => !order.includes(item.id))];
+    }
+    if (proposal.kind === "revise_pending_wording")
+        reviseWording(next, proposal, now);
+    if (proposal.kind === "split_subgoal" || proposal.kind === "mark_blocked_superseded")
+        splitOrBlock(next, proposal, now);
+    if (proposal.kind === "revise_criterion")
+        reviseCriterion(next, proposal, now);
+    if (proposal.kind !== "annotate_ledger")
+        next.updatedAt = now;
+    return next;
+}
+function reviseWording(plan, proposal, now) {
+    const target = goal(plan, targets(proposal)[0]);
+    if (target === undefined)
+        return;
+    target.title = revised(proposal, "revisedTitle", "title") ?? target.title;
+    target.objective = revised(proposal, "revisedObjective", "objective") ?? target.objective;
+    target.steeringEvidence = proposal.evidence;
+    target.steeringRationale = proposal.rationale;
+    target.updatedAt = now;
+}
+function splitOrBlock(plan, proposal, now) {
+    const target = goal(plan, targets(proposal)[0]);
+    if (target === undefined)
+        return;
+    const replacements = children(proposal).map((item, index) => makeGoal(plan, item, proposal.evidence, now, index + 1));
+    target.steeringEvidence = proposal.evidence;
+    target.steeringRationale = proposal.rationale;
+    target.updatedAt = now;
+    if (replacements.length === 0) {
+        target.status = "blocked";
+        target.steeringStatus = "blocked";
+        target.blockedReason = proposal.blockedReason ?? proposal.rationale;
+    }
+    else {
+        target.steeringStatus = "superseded";
+        target.supersededBy = replacements.map((item) => item.id);
+        for (const item of replacements)
+            item.supersedes = [target.id];
+        plan.goals.splice(plan.goals.indexOf(target) + 1, 0, ...replacements);
+    }
+    if (plan.activeGoalId === target.id)
+        delete plan.activeGoalId;
+}
+function reviseCriterion(plan, proposal, now) {
+    const target = goal(plan, targets(proposal)[0]);
+    const index = target?.successCriteria.findIndex((item) => item.id === proposal.criterionId) ?? -1;
+    const current = target?.successCriteria[index];
+    if (target === undefined || current === undefined)
+        return;
+    const model = read(proposal, "userModel");
+    target.successCriteria[index] = { ...current, scenario: text(proposal, "scenario") ?? current.scenario, expectedEvidence: text(proposal, "expectedEvidence") ?? current.expectedEvidence, userModel: isModel(model) ? model : current.userModel };
+    target.updatedAt = now;
+}
+function isProposal(value) {
+    return isPlain(value) && isKind(read(value, "kind")) && isSource(read(value, "source")) && isText(read(value, "evidence")) && isText(read(value, "rationale"));
+}
+export function parseUlwLoopSteeringDirective(text) {
+    const match = /(?:^|\s)(?:OMO_ULW_LOOP_STEER|omo\.ulw-loop\.steer|omo ulw-loop steer):\s*([\s\S]+)$/u.exec(text);
+    if (match?.[1] === undefined)
+        return null;
+    try {
+        const parsed = JSON.parse(match[1].trim());
+        return isProposal(parsed) ? parsed : null;
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+}
+export async function steerUlwLoop(repoRoot, proposal, scope) {
+    return withUlwLoopMutationLock(repoRoot, scope, async () => {
+        const plan = await readUlwLoopPlan(repoRoot, scope);
+        const key = proposal.idempotencyKey ?? proposal.promptSignature;
+        const prior = key === undefined ? undefined : (await readSteeringLedgerEntries(repoRoot, scope)).find((entry) => entry.steering?.invariant.accepted === true && (entry.idempotencyKey === key || entry.steering.idempotencyKey === key || entry.steering.promptSignature === key));
+        if (prior?.steering !== undefined)
+            return { plan, accepted: true, audit: { ...prior.steering, deduped: true }, rejectedReasons: [], deduped: true };
+        const audit = validateUlwLoopSteeringProposal(plan, proposal);
+        const accepted = audit.invariant.accepted;
+        const next = accepted ? applySteeringMutation(plan, proposal, audit) : plan;
+        const finalAudit = { ...audit, before: plan };
+        if (accepted)
+            finalAudit.after = next;
+        if (accepted)
+            await writePlan(repoRoot, next, scope);
+        await appendLedger(repoRoot, ledgerEntry(proposal, finalAudit, proposal.now?.toISOString() ?? iso()), scope);
+        return { plan: next, accepted, audit: finalAudit, rejectedReasons: audit.invariant.rejectedReasons, deduped: false };
+    });
+}
+function ledgerEntry(proposal, audit, at) {
+    const entry = { at, kind: audit.invariant.accepted ? (proposal.kind === "revise_criterion" ? "criteria_revised" : "steering_accepted") : "steering_rejected", evidence: proposal.evidence, message: proposal.rationale, steering: audit, mutationKind: proposal.kind };
+    const goalId = audit.targetGoalIds[0];
+    if (goalId !== undefined)
+        entry.goalId = goalId;
+    if (proposal.criterionId !== undefined)
+        entry.criterionId = proposal.criterionId;
+    if (proposal.idempotencyKey !== undefined)
+        entry.idempotencyKey = proposal.idempotencyKey;
+    if (audit.before !== undefined)
+        entry.before = audit.before;
+    if (audit.after !== undefined)
+        entry.after = audit.after;
+    return entry;
+}

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

@@ -0,0 +1,5 @@
+export * from "./command-types.js";
+export * from "./constants.js";
+export * from "./domain-types.js";
+export * from "./runtime.js";
+export * from "./steering-types.js";

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

@@ -0,0 +1,5 @@
+export * from "./command-types.js";
+export * from "./constants.js";
+export * from "./domain-types.js";
+export * from "./runtime.js";
+export * from "./steering-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",
 						"timeout": 10,
-						"statusMessage": "LazyCodex(0.1.0): Checking Ulw-Loop Steering"
+						"statusMessage": "LazyCodex(4.9.1): Checking Ulw-Loop Steering"
 					}
 				]
 			}
@@ -20,7 +20,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use",
 						"timeout": 5,
-						"statusMessage": "LazyCodex(0.1.0): Enforcing Unlimited Ulw-Loop Budget"
+						"statusMessage": "LazyCodex(4.9.1): Enforcing Unlimited Ulw-Loop Budget"
 					}
 				]
 			}

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

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-ulw-loop",
-	"version": "0.1.0",
+	"version": "4.9.1",
 	"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

@@ -9,12 +9,12 @@ metadata:
 
 Use this skill when the user asks for `ulw-loop`, `ulw`, durable goal execution, evidence-led work, manual QA, or checkpointed long-running delivery.
 
-This Codex skill is intentionally compact to avoid adding a large operating manual to an already-full conversation. The full workflow lives in `references/full-workflow.md`. Read only the sections needed for the current phase, then execute them exactly.
+This skill is intentionally compact. The full workflow lives in `references/full-workflow.md`. Read only the sections needed for the current phase, then execute them exactly.
 
 ## Required First Steps
 
 1. Open `references/full-workflow.md`.
-2. Read through **Bootstrap**, **Execution Loop**, and the **Manual-QA channels** table before running any ULW command or recording evidence.
+2. Read through **Bootstrap** (including its tier triage), **Execution Loop**, and the **Manual-QA channels** table before running any ULW command or recording evidence.
 3. If the task has code edits, tests, QA, or commit work, follow the full workflow's delegation and evidence rules. Tests alone never prove done.
 
 ## Non-Negotiables
@@ -22,15 +22,15 @@ This Codex skill is intentionally compact to avoid adding a large operating manu
 - Use the ulw-loop CLI state under `.omo/ulw-loop`; do not hand-edit goal state.
 - After any compaction or context loss, re-read brief + goals + ledger FIRST (`omo sparkshell cat .omo/ulw-loop/ledger.jsonl` or read directly) plus `omo ulw-loop status --json`, then resume; never re-plan from scratch.
 - If `omo ulw-loop create-goals` says the existing aggregate is already complete, start unrelated new work with a fresh `--session-id <new-id>` instead of steering or forcing the completed default state. Use `--force` only to intentionally overwrite completed evidence.
-- Every success criterion needs observable evidence from a real channel: tmux, HTTP, browser, or computer-use.
+- Every success criterion needs observable evidence from a real surface: a channel (tmux, HTTP, browser, computer-use) or, for CLI- or data-shaped criteria, an auxiliary surface (CLI stdout, DB diff, parsed config dump).
 - Record evidence through the CLI only after cleanup receipts are available.
 - Delegate code edits, test writes, fixes, and QA execution to right-sized Codex subagents when the workflow requires it.
-- Every `spawn_agent` message starts with `TASK:`, then names `DELIVERABLE`, `SCOPE`, and `VERIFY`; put role and specialty instructions inside `message` because the Codex tool schema only accepts `task_name`, `message`, and `fork_turns`; prefer `fork_turns: "none"` unless full history is truly required.
-- Plan and reviewer agents may run for a long time; spawn them in the background, keep doing independent root work, and poll with short wait_agent cycles. Never use a single long blocking wait for them.
+- Every `multi_agent_v1.spawn_agent` message starts with `TASK:`, then names `DELIVERABLE`, `SCOPE`, and `VERIFY`; put role and specialty instructions inside `message`; use `fork_context: false` unless full history is truly required.
+- Plan and reviewer agents may run for a long time; spawn them in the background, keep doing independent root work, and poll with short `multi_agent_v1.wait_agent` cycles. Never use a single long blocking wait for them.
 - For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long reading, testing, or review passes, and `BLOCKED: <reason>` only when it cannot progress.
-- While any child is active, keep the parent visibly alive with brief status updates that include active subagent count, agent names, latest `WORKING:` phase, and whether the parent is waiting for mailbox updates.
-- Track spawned agent names locally. Use `wait_agent` for mailbox signals, not proof of completion. A timeout only means no new mailbox update arrived; after a timeout, run a single `list_agents` check for the named child when you need reassurance. If it is running or its latest message is `WORKING:`, treat it as alive.
-- Do not use `list_agents` as a polling loop or status feed; it can replay large payloads. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running. Then record inconclusive and respawn a smaller `fork_turns: "none"` task with the missing deliverable.
+- Track spawned agent names locally. Use `multi_agent_v1.wait_agent` for mailbox signals, not proof of completion. A timeout only means no new mailbox update arrived. Treat a running child as alive.
+- While children run, surface the active subagent count, agent names, and latest `WORKING:` phase.
+- Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running. Then record inconclusive and respawn a smaller `fork_context: false` task with the missing deliverable.
 - Use `git-master` for git-tracked edits: inspect recent and touched-path commit history, then commit each verified work unit atomically in the repository's observed language, scope, and message style with only that unit's files staged.
 
 ## Codex Tool Mapping
@@ -39,11 +39,11 @@ The full workflow may mention OpenCode-style orchestration examples. In Codex, t
 
 | Workflow intent | Codex tool |
 | --- | --- |
-| Plan agent | `spawn_agent({"task_name":"...","message":"TASK: act as a planning agent. ...","fork_turns":"none"})` |
-| Search/read-only worker | `spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})` |
-| Implementation or QA worker | `spawn_agent({"task_name":"...","message":"TASK: act as an implementation or QA worker. ...","fork_turns":"none"})` |
-| Final verification reviewer | `spawn_agent({"task_name":"...","message":"TASK: act as a rigorous reviewer. ...","fork_turns":"none"})` |
-| Wait for background result | `wait_agent(...)` |
-| Clean up finished worker | `close_agent(...)` |
+| Plan agent | `multi_agent_v1.spawn_agent({"message":"TASK: act as a planning agent. ...","fork_context":false})` |
+| Search/read-only worker | `multi_agent_v1.spawn_agent({"message":"TASK: act as an explorer. ...","fork_context":false})` |
+| Implementation or QA worker | `multi_agent_v1.spawn_agent({"message":"TASK: act as an implementation or QA worker. ...","fork_context":false})` |
+| Final verification reviewer | `multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","fork_context":false})` |
+| Wait for background result | `multi_agent_v1.wait_agent(...)` |
+| Clean up finished worker | `multi_agent_v1.close_agent(...)` |
 
 When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`.