oh-my-opencode 4.16.3 → 4.17.0

package/packages/omo-codex/plugin/components/ulw-loop/dist/quality-gate-verdicts.js

@@ -0,0 +1,20 @@
+import { literal, invalid, textField } from "./quality-gate-fields.js";
+export function passedVerdict(value, field) {
+    if (value === "not_applicable")
+        invalid(`${field} must not be not_applicable.`, field);
+    return literal(value, "passed", field);
+}
+export function codeQualityStatusField(value, field) {
+    if (value === "CLEAR" || value === "WATCH")
+        return value;
+    invalid(`${field} must be CLEAR or WATCH.`, field);
+}
+export function adversarialVerdict(row, field) {
+    const value = row["verdict"];
+    if (value === "passed")
+        return { verdict: "passed" };
+    if (value === "not_applicable") {
+        return { verdict: "not_applicable", reason: textField(row["reason"], `${field}.reason`) };
+    }
+    invalid(`${field} must be passed or not_applicable with a reason.`, field);
+}

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

@@ -9,5 +9,6 @@ export interface QualityGateFs {
 export interface ValidateQualityGateOptions {
     readonly repoRoot: string;
     readonly fs: QualityGateFs;
+    readonly currentAttemptDir?: string;
 }
 export declare function validateQualityGate(input: unknown, opts?: ValidateQualityGateOptions): UlwLoopQualityGate;

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

@@ -1,5 +1,7 @@
 import { resolve } from "node:path";
+import { isWithinAttemptDir } from "./paths.js";
 import { emptyBlockers, invalid, literal, numberField, section, stringArray, textField, } from "./quality-gate-fields.js";
+import { adversarialVerdict, codeQualityStatusField, passedVerdict } from "./quality-gate-verdicts.js";
 const REVIEWER_ROLES = {
     codeReview: "lazycodex-code-reviewer",
     manualQa: "lazycodex-qa-executor",
@@ -32,11 +34,6 @@ function kindField(value, field) {
         return value;
     invalid(`${field} must be a supported artifact kind.`, field);
 }
-function passedVerdict(value, field) {
-    if (value === "not_applicable")
-        invalid(`${field} must not be not_applicable.`, field);
-    return literal(value, "passed", field);
-}
 function artifactCompatible(surface, kind) {
     switch (surface) {
         case "cli":
@@ -59,9 +56,13 @@ function checkFile(path, field, opts) {
     const absolute = resolve(opts.repoRoot, path);
     if (!opts.fs.existsSync(absolute))
         invalid(`${field} must point to an existing artifact.`, field);
-    const stat = opts.fs.statSync(absolute);
-    if (stat.size <= 0)
+    if (opts.fs.statSync(absolute).size <= 0)
         invalid(`${field} must point to a non-empty artifact.`, field);
+    if (opts.currentAttemptDir !== undefined) {
+        const attemptRoot = resolve(opts.repoRoot, opts.currentAttemptDir);
+        if (!isWithinAttemptDir(absolute, attemptRoot))
+            invalid(`${field} (${path}) must point to an artifact from the current attempt (${opts.currentAttemptDir}).`, field);
+    }
 }
 function artifactMap(refs) {
     const byId = new Map();
@@ -118,7 +119,7 @@ export function validateQualityGate(input, opts) {
         codeReview: {
             by: reviewerRoleField(codeReview["by"], REVIEWER_ROLES.codeReview, "codeReview.by"),
             recommendation: literal(codeReview["recommendation"], "APPROVE", "codeReview.recommendation"),
-            codeQualityStatus: literal(codeReview["codeQualityStatus"], "CLEAR", "codeReview.codeQualityStatus"),
+            codeQualityStatus: codeQualityStatusField(codeReview["codeQualityStatus"], "codeReview.codeQualityStatus"),
             reportPath: codeReportPath,
             evidence: textField(codeReview["evidence"], "codeReview.evidence"),
             blockers: emptyBlockers(codeReview["blockers"], "codeReview.blockers"),
@@ -182,12 +183,14 @@ function parseAdversarialCases(value, byId) {
     return value.map((item, index) => {
         const row = section(item, `manualQa.adversarialCases[${index}]`);
         const artifacts = referencedArtifacts(row["artifactRefs"], `manualQa.adversarialCases[${index}].artifactRefs`, byId);
+        const verdictInfo = adversarialVerdict(row, `manualQa.adversarialCases[${index}]`);
         return {
             id: textField(row["id"], `manualQa.adversarialCases[${index}].id`),
             criterionRef: textField(row["criterionRef"], `manualQa.adversarialCases[${index}].criterionRef`),
             scenario: textField(row["scenario"], `manualQa.adversarialCases[${index}].scenario`),
             expectedBehavior: textField(row["expectedBehavior"], `manualQa.adversarialCases[${index}].expectedBehavior`),
-            verdict: passedVerdict(row["verdict"], `manualQa.adversarialCases[${index}].verdict`),
+            verdict: verdictInfo.verdict,
+            ...(verdictInfo.reason === undefined ? {} : { reason: verdictInfo.reason }),
             artifactRefs: artifacts.map((artifact) => artifact.id),
         };
     });

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

@@ -0,0 +1,3 @@
+import type { PreToolUsePayload } from "./codex-hook.js";
+export declare function applySpawnGuards(payload: PreToolUsePayload): string;
+export declare function runSpawnGuardCli(stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream): Promise<void>;

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

@@ -0,0 +1,148 @@
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parsePreToolUsePayload } from "./codex-hook.js";
+import { isFinalRunCompletionCandidate } from "./goal-status.js";
+import { ulwLoopAttemptEvidenceDir, ulwLoopDir } from "./paths.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 DEFAULT_FANOUT_LIMIT = 60;
+const GATE_MESSAGE_PATTERN = /lazycodex-gate-reviewer|final gate review/i;
+export function applySpawnGuards(payload) {
+    if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name))
+        return "";
+    const stateDir = ulwLoopDir(payload.cwd, { sessionId: payload.session_id });
+    const plan = readPlan(join(stateDir, "goals.json"));
+    if (plan === null)
+        return "";
+    const fanOutDenial = consumeFanOutBudget(stateDir);
+    if (fanOutDenial !== null)
+        return deny(fanOutDenial);
+    const missingArtifact = missingGateArtifact(payload, plan);
+    if (missingArtifact !== null)
+        return deny(`spawn code-review + QA first; gate audits their artifacts: missing ${missingArtifact}`);
+    return "";
+}
+export async function runSpawnGuardCli(stdin, stdout) {
+    try {
+        const chunks = [];
+        for await (const chunk of stdin)
+            chunks.push(Buffer.from(chunk));
+        const payload = parsePreToolUsePayload(Buffer.concat(chunks).toString("utf8"));
+        if (payload === null)
+            return;
+        const output = applySpawnGuards(payload);
+        if (output.length > 0)
+            stdout.write(output);
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return;
+    }
+}
+// Per-session spawn counter; depth/lineage tracking is descoped — this is a
+// total-volume backstop against fan-out explosions, not a recursion tracker.
+function consumeFanOutBudget(stateDir) {
+    const counterPath = join(stateDir, "spawn-count.json");
+    const count = readCount(counterPath) + 1;
+    writeFileSync(counterPath, JSON.stringify({ count }));
+    const limit = fanOutLimit();
+    if (count <= limit)
+        return null;
+    return `ulw-loop spawn fan-out cap reached (${count}/${limit}). Consolidate work into the agents already running, or raise OMO_SPAWN_FANOUT_LIMIT if this volume is intentional.`;
+}
+function missingGateArtifact(payload, plan) {
+    if (!isGateReviewerSpawn(payload.tool_input))
+        return null;
+    const goal = plan.goals.find((candidate) => isFinalRunCompletionCandidate(plan, candidate));
+    if (goal === undefined || goal.status === "complete")
+        return null;
+    if (!goal.successCriteria.every((criterion) => criterion.status === "pass"))
+        return null;
+    const scope = { sessionId: payload.session_id };
+    if (plan.evidenceLayoutVersion === 2) {
+        const attemptDir = ulwLoopAttemptEvidenceDir(goal.id, goal.attempt, scope);
+        for (const name of [`${goal.id}-code-review.md`, `${goal.id}-manual-qa.md`]) {
+            const relative = `${attemptDir}/${name}`;
+            if (!isNonEmptyFile(join(payload.cwd, relative)))
+                return relative;
+        }
+        return null;
+    }
+    const flatReport = `.omo/evidence/${goal.id}-code-review.md`;
+    if (!isNonEmptyFile(join(payload.cwd, flatReport)))
+        return flatReport;
+    // v1 manual-QA approximation: any other non-empty evidence file counts.
+    if (!hasOtherEvidenceFile(join(payload.cwd, ".omo", "evidence"), `${goal.id}-code-review.md`))
+        return `.omo/evidence/<any manual-QA artifact besides ${goal.id}-code-review.md>`;
+    return null;
+}
+function isGateReviewerSpawn(toolInput) {
+    if (typeof toolInput !== "object" || toolInput === null)
+        return false;
+    const record = toolInput;
+    const agentType = record["agent_type"];
+    if (typeof agentType === "string")
+        return agentType === "lazycodex-gate-reviewer";
+    const message = record["message"];
+    return typeof message === "string" && GATE_MESSAGE_PATTERN.test(message);
+}
+function deny(reason) {
+    return `${JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "deny",
+            permissionDecisionReason: reason,
+            additionalContext: reason,
+        },
+    })}\n`;
+}
+function fanOutLimit() {
+    const raw = process.env["OMO_SPAWN_FANOUT_LIMIT"];
+    if (raw === undefined)
+        return DEFAULT_FANOUT_LIMIT;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_FANOUT_LIMIT;
+}
+function isNonEmptyFile(path) {
+    try {
+        return existsSync(path) && statSync(path).size > 0;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return false;
+        throw error;
+    }
+}
+function hasOtherEvidenceFile(evidenceDir, excludedName) {
+    try {
+        return readdirSync(evidenceDir).some((name) => name !== excludedName && isNonEmptyFile(join(evidenceDir, name)));
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return false;
+        throw error;
+    }
+}
+function readCount(counterPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(counterPath, "utf8"));
+        return typeof parsed["count"] === "number" && parsed["count"] >= 0 ? parsed["count"] : 0;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return 0;
+        throw error;
+    }
+}
+function readPlan(goalsPath) {
+    try {
+        return JSON.parse(readFileSync(goalsPath, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return null;
+        throw error;
+    }
+}

package/packages/omo-codex/plugin/components/ulw-loop/dist/stop-resume-hook.d.ts

@@ -0,0 +1,2 @@
+export declare function runStopResumeHook(input: unknown): string;
+export declare function runStopResumeHookCli(stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream): Promise<void>;

package/packages/omo-codex/plugin/components/ulw-loop/dist/stop-resume-hook.js

@@ -0,0 +1,209 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { normalizeUlwLoopSessionId, ulwLoopDir } from "./paths.js";
+// Turn-death recovery only: Codex emits Stop when a turn ends, so a run that
+// dies mid-turn (crash, kill, context blowup before any Stop) never reaches
+// this handler. Mid-turn stalls are out of scope by design.
+const RESUME_CAP = 2;
+// Mirrors start-work-continuation's context-pressure bail-out: injecting a
+// resume directive into an already-overflowing context makes things worse.
+const CONTEXT_PRESSURE_MARKERS = [
+    "context compacted",
+    "context_length_exceeded",
+    "skill descriptions were shortened",
+    "context_too_large",
+    "codex ran out of room in the model's context window",
+    "your input exceeds the context window",
+    "long threads and multiple compactions",
+];
+export function runStopResumeHook(input) {
+    const payload = parseStopPayload(input);
+    if (payload === null || payload.stop_hook_active)
+        return "";
+    if (transcriptShowsContextPressure(payload.transcript_path))
+        return "";
+    if (boulderContinuationWillFire(payload.cwd, payload.session_id))
+        return "";
+    const stateDir = ulwLoopDir(payload.cwd, { sessionId: payload.session_id });
+    const plan = readPlan(join(stateDir, "goals.json"));
+    if (plan === null || plan.aggregateCompletion?.status === "complete")
+        return "";
+    const goal = resumableGoal(plan);
+    if (goal === undefined)
+        return "";
+    if (!consumeResumeBudget(stateDir, goal.id))
+        return "";
+    const output = {
+        decision: "block",
+        reason: renderResumeDirective(plan, goal, payload.session_id),
+    };
+    return JSON.stringify(output);
+}
+export async function runStopResumeHookCli(stdin, stdout) {
+    try {
+        const chunks = [];
+        for await (const chunk of stdin)
+            chunks.push(Buffer.from(chunk));
+        const output = runStopResumeHook(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+        if (output.length > 0)
+            stdout.write(output);
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return;
+    }
+}
+function resumableGoal(plan) {
+    const active = plan.goals.find((goal) => goal.id === plan.activeGoalId);
+    if (active !== undefined && isResumableStatus(active.status))
+        return active;
+    return plan.goals.find((goal) => isResumableStatus(goal.status));
+}
+function isResumableStatus(status) {
+    return status === "pending" || status === "in_progress";
+}
+// Two-strike cap keyed on ledger movement: an unchanged ledger.jsonl line
+// count across resumes means the loop is not progressing. The stuck marker is
+// a separate file — a ledger append would change the count and self-reset.
+function consumeResumeBudget(stateDir, goalId) {
+    const ledgerLineCount = countLedgerLines(join(stateDir, "ledger.jsonl"));
+    const counterPath = join(stateDir, `auto-resume-${goalId}.json`);
+    const previous = readCounter(counterPath);
+    const count = previous !== null && previous.ledgerLineCount === ledgerLineCount ? previous.count : 0;
+    if (count >= RESUME_CAP) {
+        writeFileSync(join(stateDir, `auto-resume-${goalId}.stuck`), `no ledger progress after ${count} resumes\n`);
+        return false;
+    }
+    writeFileSync(counterPath, JSON.stringify({ count: count + 1, ledgerLineCount }));
+    return true;
+}
+function renderResumeDirective(plan, goal, sessionId) {
+    const normalized = normalizeUlwLoopSessionId(sessionId);
+    const option = normalized !== null && plan.goalsPath.includes(`/${normalized}/`) ? ` --session-id ${normalized}` : "";
+    return [
+        `The ulw-loop run in this session still has unfinished goals (next: ${goal.id} — ${goal.title}).`,
+        "The turn ended before the loop completed. Resume it now:",
+        `1. Run \`omo ulw-loop status${option} --json\` to reload the plan, the active goal, and currentAttemptDir.`,
+        "2. Continue the active goal's remaining success criteria, recording evidence with record-evidence.",
+        `3. Checkpoint through \`omo ulw-loop checkpoint${option}\` when the goal's criteria are proven.`,
+        "If the loop is genuinely blocked on the user, checkpoint the goal as blocked with the reason instead.",
+    ].join("\n");
+}
+function readPlan(goalsPath) {
+    try {
+        return JSON.parse(readFileSync(goalsPath, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return null;
+        throw error;
+    }
+}
+function countLedgerLines(ledgerPath) {
+    try {
+        return readFileSync(ledgerPath, "utf8").split("\n").filter(Boolean).length;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return 0;
+        throw error;
+    }
+}
+function readCounter(counterPath) {
+    try {
+        if (!existsSync(counterPath))
+            return null;
+        const parsed = JSON.parse(readFileSync(counterPath, "utf8"));
+        if (typeof parsed["count"] !== "number" || typeof parsed["ledgerLineCount"] !== "number")
+            return null;
+        return { count: parsed["count"], ledgerLineCount: parsed["ledgerLineCount"] };
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return null;
+        throw error;
+    }
+}
+// Local ~10-LOC approximation of start-work-continuation's boulder check (no
+// cross-component import allowed): any continuable work for this session means
+// that hook owns the Stop event, so this one stays silent.
+function boulderContinuationWillFire(cwd, sessionId) {
+    try {
+        const raw = JSON.parse(readFileSync(join(cwd, ".omo", "boulder.json"), "utf8"));
+        const works = raw["works"];
+        // The flat legacy shape has no works map: the top level is the single work.
+        const entries = typeof works === "object" && works !== null ? Object.values(works) : [raw];
+        return entries.some((work) => {
+            if (typeof work !== "object" || work === null)
+                return false;
+            const entry = work;
+            const sessionIds = Array.isArray(entry["session_ids"]) ? entry["session_ids"] : [];
+            const continuable = entry["status"] === "active" || entry["status"] === "paused";
+            return continuable && sessionIds.includes(`codex:${sessionId}`) && boulderPlanHasRemainingTask(cwd, entry);
+        });
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return false;
+        throw error;
+    }
+}
+function transcriptShowsContextPressure(transcriptPath) {
+    try {
+        const transcript = readFileSync(transcriptPath, "utf8").toLowerCase();
+        return CONTEXT_PRESSURE_MARKERS.some((marker) => transcript.includes(marker));
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return false;
+        throw error;
+    }
+}
+// start-work-continuation only fires while its plan checklist has remaining
+// items; a boulder work whose plan is exhausted (or unreadable) leaves the
+// Stop event to this hook.
+function boulderPlanHasRemainingTask(cwd, entry) {
+    const activePlan = entry["active_plan"];
+    if (typeof activePlan !== "string" || activePlan.trim().length === 0)
+        return false;
+    const planPath = isAbsolute(activePlan) ? activePlan : join(cwd, activePlan);
+    const worktree = entry["worktree_path"];
+    const candidates = typeof worktree === "string" && worktree.trim().length > 0 && !isAbsolute(activePlan)
+        ? [join(isAbsolute(worktree) ? worktree : join(cwd, worktree), activePlan), planPath]
+        : [planPath];
+    for (const candidate of candidates) {
+        try {
+            return readFileSync(candidate, "utf8")
+                .split(/\r?\n/)
+                .some((line) => line.startsWith("- [ ] "));
+        }
+        catch (error) {
+            if (!(error instanceof Error))
+                throw error;
+        }
+    }
+    return false;
+}
+function parseStopPayload(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    const record = value;
+    const optionalMessage = record["last_assistant_message"];
+    const valid = record["hook_event_name"] === "Stop" &&
+        typeof record["session_id"] === "string" &&
+        typeof record["turn_id"] === "string" &&
+        typeof record["transcript_path"] === "string" &&
+        typeof record["cwd"] === "string" &&
+        typeof record["model"] === "string" &&
+        typeof record["permission_mode"] === "string" &&
+        typeof record["stop_hook_active"] === "boolean" &&
+        (optionalMessage === undefined || typeof optionalMessage === "string");
+    if (!valid)
+        return null;
+    return {
+        session_id: record["session_id"],
+        cwd: record["cwd"],
+        transcript_path: record["transcript_path"],
+        stop_hook_active: record["stop_hook_active"],
+    };
+}

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 4.16.3) Checking Ulw-Loop Steering"
+						"statusMessage": "(OmO 4.17.0) Checking Ulw-Loop Steering"
 					}
 				]
 			}
@@ -20,7 +20,30 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use",
 						"timeout": 5,
-						"statusMessage": "(OmO 4.16.3) Enforcing Unlimited Ulw-Loop Budget"
+						"statusMessage": "(OmO 4.17.0) Enforcing Unlimited Ulw-Loop Budget"
+					}
+				]
+			},
+			{
+				"matcher": "^(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 4.17.0) Guarding Ulw-Loop Spawns"
+					}
+				]
+			}
+		],
+		"Stop": [
+			{
+				"hooks": [
+					{
+						"type": "command",
+						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook stop",
+						"timeout": 10,
+						"statusMessage": "(OmO 4.17.0) 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": "4.16.3",
+	"version": "4.17.0",
 	"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

@@ -23,29 +23,28 @@ This skill is intentionally compact. The full workflow lives in `references/full
 - After any compaction or context loss, re-read brief + goals + ledger FIRST 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 surface: a channel (terminal/TUI via the xterm.js web terminal, 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.
+- Evidence is bound to its capture commit; a later fix, rebase, or merge makes it stale — re-run at the current HEAD and re-record, never relabel or regenerate. Record only after cleanup receipts exist.
 - Delegate code edits, test writes, fixes, and QA execution to right-sized Codex subagents when the workflow requires it.
-- 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.
+- Every `spawn_agent` message starts with `TASK:`, then names `DELIVERABLE`, `SCOPE`, and `VERIFY`; put role and specialty instructions inside `message`; use `fork_turns: "none"` (v1: `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 `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.
-- 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.
+- Track spawned agent names locally. Use `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.
+- Fallback only when the child is completed without the deliverable, ack-only after `followup_task`, explicitly `BLOCKED:`, or no longer running. Then record inconclusive and respawn a smaller `fork_turns: "none"` 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
 
-The full workflow may mention OpenCode-style orchestration examples. In Codex, translate them to native tools:
+Codex exposes ONE subagent surface per session — check your tool list. GPT-5.6 (sol/terra) get the flat MultiAgentV2 tools (primary); GPT-5.5 and gpt-5.6-luna get the namespaced `multi_agent_v1.*` set (fallback row). The workflow's orchestration examples map to:
 
-| Workflow intent | Codex tool |
+| Intent | MultiAgentV2 (gpt-5.6 sol/terra) |
 | --- | --- |
-| 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(...)` |
-
-Flat `spawn_agent` requiring `task_name` instead (`multi_agent_v2`)? Rewrite rows: add `"task_name"`, `"fork_context":false` → `"fork_turns":"none"`, `wait_agent` takes only `timeout_ms`, no `close_agent` — finished agents end on their own.
+| Spawn a worker | `spawn_agent({"task_name":"<lower_snake_id>","message":"TASK: act as <role>. ...","fork_turns":"none"})` — `task_name`+`message` required; `fork_turns:"none"` = no parent history; do NOT set `agent_type`/`model`/`reasoning_effort` |
+| Re-task an idle worker (wakes it) | `followup_task({"target":"<name>","message":"..."})` |
+| Send context without interrupting | `send_message({"target":"<name>","message":"..."})` |
+| Wait for a mailbox signal | `wait_agent({"timeout_ms":<ms>})` — any live worker; a timeout only means no new update |
+| Enumerate / stop a runaway | `list_agents()` / `interrupt_agent({"target":"<name>"})` — no `close_agent`; finished workers end on their own |
+
+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`.