lazycodex-ai 5.1.11 → 5.1.13

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

@@ -4360,25 +4360,82 @@ function readAll(stdin) {
 
 // components/ulw-loop/src/spawn-guard.ts
 import { mkdirSync as mkdirSync3 } from "node:fs";
-import { join as join7 } from "node:path";
+import { join as join8 } from "node:path";
+
+// components/ulw-loop/src/registered-agent-roles.ts
+import { readdirSync as readdirSync3, readFileSync as readFileSync6 } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname as dirname3, join as join6, resolve as resolve5 } from "node:path";
+var NAME_LINE = /^\s*name\s*=\s*"([^"\n]+)"\s*(?:#.*)?$/m;
+var AGENT_TABLE = /^\s*\[agents\.(?:"([^"\n]+)"|([A-Za-z0-9_-]+))\]\s*(?:#.*)?$/gm;
+function readText(path) {
+  try {
+    return readFileSync6(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+function standaloneRoleNames(agentsDir) {
+  let entries;
+  try {
+    entries = readdirSync3(agentsDir);
+  } catch {
+    return [];
+  }
+  const names = [];
+  for (const entry of entries) {
+    if (!entry.endsWith(".toml"))
+      continue;
+    const text = readText(join6(agentsDir, entry));
+    if (text === null)
+      continue;
+    names.push(text.match(NAME_LINE)?.[1] ?? basename(entry, ".toml"));
+  }
+  return names;
+}
+function configTableRoleNames(configPath) {
+  const text = readText(configPath);
+  if (text === null)
+    return [];
+  return [...text.matchAll(AGENT_TABLE)].map((match) => match[1] ?? match[2] ?? "").filter(Boolean);
+}
+function codexDirs(cwd, env) {
+  const dirs = [resolve5(env["CODEX_HOME"]?.trim() || join6(homedir(), ".codex"))];
+  for (let dir = resolve5(cwd);; dir = dirname3(dir)) {
+    dirs.push(join6(dir, ".codex"));
+    if (dirname3(dir) === dir)
+      break;
+  }
+  return [...new Set(dirs)];
+}
+function registeredAgentRoles(cwd, env = process.env) {
+  const names = new Set;
+  for (const dir of codexDirs(cwd, env)) {
+    for (const name of standaloneRoleNames(join6(dir, "agents")))
+      names.add(name);
+    for (const name of configTableRoleNames(join6(dir, "config.toml")))
+      names.add(name);
+  }
+  return names;
+}
 
 // components/ulw-loop/src/spawn-budget-io.ts
 import { randomBytes } from "node:crypto";
-import { existsSync as existsSync7, readFileSync as readFileSync6, renameSync as renameSync2, statSync as statSync3, writeFileSync as writeFileSync2 } from "node:fs";
-import { dirname as dirname3, join as join6 } from "node:path";
+import { existsSync as existsSync7, readFileSync as readFileSync7, renameSync as renameSync2, statSync as statSync3, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname4, join as join7 } from "node:path";
 function readAdmissionBreaker(sessionId) {
   const dataDir = process.env["PLUGIN_DATA"];
   if (typeof dataDir !== "string")
     return null;
   try {
-    const value = JSON.parse(readFileSync6(join6(dataDir, "spawn-breaker", `${sessionId}.json`), "utf8"));
+    const value = JSON.parse(readFileSync7(join7(dataDir, "spawn-breaker", `${sessionId}.json`), "utf8"));
     return typeof value === "object" && value !== null && "reason" in value && typeof value.reason === "string" ? value.reason : "capacity limit";
   } catch {
     return null;
   }
 }
 function atomicWriteJson(targetPath, data) {
-  const tmp = join6(dirname3(targetPath), `.tmp-${randomBytes(6).toString("hex")}`);
+  const tmp = join7(dirname4(targetPath), `.tmp-${randomBytes(6).toString("hex")}`);
   writeFileSync2(tmp, JSON.stringify(data));
   renameSync2(tmp, targetPath);
 }
@@ -4393,7 +4450,7 @@ function isNonEmptyFile(path) {
 }
 function readCount(counterPath) {
   try {
-    const parsed = JSON.parse(readFileSync6(counterPath, "utf8"));
+    const parsed = JSON.parse(readFileSync7(counterPath, "utf8"));
     return typeof parsed === "object" && parsed !== null && "count" in parsed && typeof parsed.count === "number" && parsed.count >= 0 ? parsed.count : 0;
   } catch (error) {
     if (error instanceof Error)
@@ -4403,7 +4460,7 @@ function readCount(counterPath) {
 }
 function readCounts(counterPath) {
   try {
-    const parsed = JSON.parse(readFileSync6(counterPath, "utf8"));
+    const parsed = JSON.parse(readFileSync7(counterPath, "utf8"));
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
       return {};
     const counts = {};
@@ -4433,11 +4490,15 @@ var LAZYCODEX_SPAWN_ROLES = new Set([
   "momus",
   "plan"
 ]);
-function spawnRoleDenial(input) {
+function spawnRoleDenial(input, registeredRoles = () => new Set) {
   const role = typeof input === "object" && input !== null && "agent_type" in input ? input.agent_type : undefined;
   if (typeof role === "string" && LAZYCODEX_SPAWN_ROLES.has(role))
     return null;
-  return `LazyCodex requires an explicit registered agent_type: ${[...LAZYCODEX_SPAWN_ROLES].join(", ")}. Received ${JSON.stringify(role) ?? "no agent_type"}. Use the matching role and fork_turns: "none" (V2) or fork_context: false (V1), unless full history is deliberately required. The hook cannot see the tool schema; if agent_type is unavailable, stop and report incompatible role routing rather than spawning a generic agent. Describing a role in message does not select its TOML.`;
+  const registered = typeof role === "string" && role.trim() !== "" ? registeredRoles() : new Set;
+  if (typeof role === "string" && registered.has(role))
+    return null;
+  const known = [...new Set([...LAZYCODEX_SPAWN_ROLES, ...registered])];
+  return `LazyCodex requires an explicit registered agent_type: ${known.join(", ")}. Received ${JSON.stringify(role) ?? "no agent_type"}. Use the matching role and fork_turns: "none" (V2) or fork_context: false (V1), unless full history is deliberately required. The hook cannot see the tool schema; if agent_type is unavailable, stop and report incompatible role routing rather than spawning a generic agent. Describing a role in message does not select its TOML.`;
 }
 
 // components/ulw-loop/src/spawn-guard.ts
@@ -4461,7 +4522,7 @@ function applySpawnGuards(payload, options = {}) {
   if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name))
     return "";
   if (resolveToolkitSurface() === "lazycodex") {
-    const reason = spawnRoleDenial(payload.tool_input);
+    const reason = spawnRoleDenial(payload.tool_input, () => registeredAgentRoles(payload.cwd));
     if (reason !== null)
       return deny(reason);
   }
@@ -4514,10 +4575,10 @@ async function runSpawnAdmissionRecorderCli(stdin, stdout) {
     const dataDir = process.env["PLUGIN_DATA"];
     if (typeof dataDir !== "string" || typeof payload["session_id"] !== "string")
       return;
-    const markerDir = join7(dataDir, "spawn-breaker");
+    const markerDir = join8(dataDir, "spawn-breaker");
     try {
       mkdirSync3(markerDir, { recursive: true });
-      atomicWriteJson(join7(markerDir, `${payload["session_id"]}.json`), {
+      atomicWriteJson(join8(markerDir, `${payload["session_id"]}.json`), {
         reason: response,
         at: new Date().toISOString()
       });
@@ -4546,7 +4607,7 @@ async function runSpawnGuardCli(stdin, stdout) {
   }
 }
 function peekFanOutBudget(stateDir) {
-  const counterPath = join7(stateDir, "spawn-count.json");
+  const counterPath = join8(stateDir, "spawn-count.json");
   const count = readCount(counterPath) + 1;
   const limit = fanOutLimit();
   if (count <= limit)
@@ -4554,7 +4615,7 @@ function peekFanOutBudget(stateDir) {
   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 consumeFanOutBudget(stateDir) {
-  const counterPath = join7(stateDir, "spawn-count.json");
+  const counterPath = join8(stateDir, "spawn-count.json");
   const count = readCount(counterPath) + 1;
   atomicWriteJson(counterPath, { count });
   const limit = fanOutLimit();
@@ -4569,7 +4630,7 @@ function consumeReviewSpawnBudget(payload, plan, stateDir) {
   const goal = plan.goals.find((candidate) => candidate.id === plan.activeGoalId) ?? plan.goals.find((candidate) => isFinalRunCompletionCandidate(plan, candidate));
   if (goal === undefined)
     return null;
-  const counterPath = join7(stateDir, "review-spawn-counts.json");
+  const counterPath = join8(stateDir, "review-spawn-counts.json");
   const limit = reviewSpawnLimit();
   const counts = readCounts(counterPath);
   const key = `${agentType}:${goal.id}:a${goal.attempt}`;
@@ -4594,13 +4655,13 @@ function missingGateArtifact(payload, plan) {
     const attemptDir = ulwLoopAttemptEvidenceDir(goal.id, goal.attempt, scope);
     for (const name of requiredArtifacts) {
       const relative = `${attemptDir}/${name}`;
-      if (!isNonEmptyFile(join7(payload.cwd, relative)))
+      if (!isNonEmptyFile(join8(payload.cwd, relative)))
         return relative;
     }
     return null;
   }
   const manualQa = `.omo/evidence/${goal.id}-manual-qa.md`;
-  return isNonEmptyFile(join7(payload.cwd, manualQa)) ? null : manualQa;
+  return isNonEmptyFile(join8(payload.cwd, manualQa)) ? null : manualQa;
 }
 function isGateReviewerSpawn(toolInput) {
   const agentType = reviewAgentType(toolInput);
@@ -4684,8 +4745,8 @@ function readPlan(repoRoot, sessionId) {
 }
 
 // components/ulw-loop/src/stop-resume-hook.ts
-import { existsSync as existsSync8, readFileSync as readFileSync7, writeFileSync as writeFileSync3 } from "node:fs";
-import { isAbsolute as isAbsolute3, join as join8, resolve as resolve5, sep as sep3 } from "node:path";
+import { existsSync as existsSync8, readFileSync as readFileSync8, writeFileSync as writeFileSync3 } from "node:fs";
+import { isAbsolute as isAbsolute3, join as join9, resolve as resolve6, sep as sep3 } from "node:path";
 var RESUME_CAP = 2;
 var CONTEXT_PRESSURE_MARKERS2 = [
   "context compacted",
@@ -4753,8 +4814,8 @@ function consumeResumeBudgetLocked(lockPath, stateDir, goalId) {
 }
 function consumeResumeBudget(stateDir, goalId) {
   const ledgerLineCount = readLedgerAt(stateDir).length;
-  const counterPath = resolve5(stateDir, `auto-resume-${goalId}.json`);
-  const stuckPath = resolve5(stateDir, `auto-resume-${goalId}.stuck`);
+  const counterPath = resolve6(stateDir, `auto-resume-${goalId}.json`);
+  const stuckPath = resolve6(stateDir, `auto-resume-${goalId}.stuck`);
   if (!isInsideDir(stateDir, counterPath) || !isInsideDir(stateDir, stuckPath))
     return false;
   const previous = readCounter(counterPath);
@@ -4768,7 +4829,7 @@ function consumeResumeBudget(stateDir, goalId) {
   return true;
 }
 function isInsideDir(dir, candidate) {
-  return candidate.startsWith(resolve5(dir) + sep3);
+  return candidate.startsWith(resolve6(dir) + sep3);
 }
 function renderResumeDirective(plan, goal, sessionId) {
   const normalized = normalizeUlwLoopSessionId(sessionId);
@@ -4796,7 +4857,7 @@ function readCounter(counterPath) {
   try {
     if (!existsSync8(counterPath))
       return null;
-    const parsed = JSON.parse(readFileSync7(counterPath, "utf8"));
+    const parsed = JSON.parse(readFileSync8(counterPath, "utf8"));
     if (typeof parsed["count"] !== "number" || typeof parsed["ledgerLineCount"] !== "number")
       return null;
     return { count: parsed["count"], ledgerLineCount: parsed["ledgerLineCount"] };
@@ -4808,7 +4869,7 @@ function readCounter(counterPath) {
 }
 function boulderContinuationWillFire(cwd, sessionId) {
   try {
-    const raw = JSON.parse(readFileSync7(join8(cwd, ".omo", "boulder.json"), "utf8"));
+    const raw = JSON.parse(readFileSync8(join9(cwd, ".omo", "boulder.json"), "utf8"));
     const works = raw["works"];
     const entries = typeof works === "object" && works !== null ? Object.values(works) : [raw];
     return entries.some((work) => {
@@ -4827,7 +4888,7 @@ function boulderContinuationWillFire(cwd, sessionId) {
 }
 function transcriptShowsContextPressure(transcriptPath) {
   try {
-    const transcript = readFileSync7(transcriptPath, "utf8").toLowerCase();
+    const transcript = readFileSync8(transcriptPath, "utf8").toLowerCase();
     return CONTEXT_PRESSURE_MARKERS2.some((marker) => transcript.includes(marker));
   } catch (error) {
     if (error instanceof Error)
@@ -4839,12 +4900,12 @@ function boulderPlanHasChecklist(cwd, entry) {
   const activePlan = entry["active_plan"];
   if (typeof activePlan !== "string" || activePlan.trim().length === 0)
     return false;
-  const planPath = isAbsolute3(activePlan) ? activePlan : join8(cwd, activePlan);
+  const planPath = isAbsolute3(activePlan) ? activePlan : join9(cwd, activePlan);
   const worktree = entry["worktree_path"];
-  const candidates = typeof worktree === "string" && worktree.trim().length > 0 && !isAbsolute3(activePlan) ? [join8(isAbsolute3(worktree) ? worktree : join8(cwd, worktree), activePlan), planPath] : [planPath];
+  const candidates = typeof worktree === "string" && worktree.trim().length > 0 && !isAbsolute3(activePlan) ? [join9(isAbsolute3(worktree) ? worktree : join9(cwd, worktree), activePlan), planPath] : [planPath];
   for (const candidate of candidates) {
     try {
-      return readFileSync7(candidate, "utf8").split(/\r?\n/).some((line) => line.startsWith("- [ ] ") || line.startsWith("- [x] ") || line.startsWith("- [X] "));
+      return readFileSync8(candidate, "utf8").split(/\r?\n/).some((line) => line.startsWith("- [ ] ") || line.startsWith("- [x] ") || line.startsWith("- [X] "));
     } catch (error) {
       if (!(error instanceof Error))
         throw error;

package/packages/omo-codex/plugin/components/ulw-loop/dist/registered-agent-roles.d.ts

@@ -0,0 +1 @@
+export declare function registeredAgentRoles(cwd: string, env?: NodeJS.ProcessEnv): ReadonlySet<string>;

package/packages/omo-codex/plugin/components/ulw-loop/dist/registered-agent-roles.js

@@ -0,0 +1,61 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+// Codex registers a role from a standalone `agents/*.toml` (keyed by its `name`, else the
+// file stem) or from an `[agents.<name>]` table in config.toml. It reads both under
+// CODEX_HOME and under a project's `.codex/`. Codex still validates the role itself (trust,
+// required fields); this only answers "does a role file declare this name".
+const NAME_LINE = /^\s*name\s*=\s*"([^"\n]+)"\s*(?:#.*)?$/m;
+const AGENT_TABLE = /^\s*\[agents\.(?:"([^"\n]+)"|([A-Za-z0-9_-]+))\]\s*(?:#.*)?$/gm;
+function readText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function standaloneRoleNames(agentsDir) {
+    let entries;
+    try {
+        entries = readdirSync(agentsDir);
+    }
+    catch {
+        return [];
+    }
+    const names = [];
+    for (const entry of entries) {
+        if (!entry.endsWith(".toml"))
+            continue;
+        const text = readText(join(agentsDir, entry));
+        if (text === null)
+            continue;
+        names.push(text.match(NAME_LINE)?.[1] ?? basename(entry, ".toml"));
+    }
+    return names;
+}
+function configTableRoleNames(configPath) {
+    const text = readText(configPath);
+    if (text === null)
+        return [];
+    return [...text.matchAll(AGENT_TABLE)].map((match) => match[1] ?? match[2] ?? "").filter(Boolean);
+}
+function codexDirs(cwd, env) {
+    const dirs = [resolve(env["CODEX_HOME"]?.trim() || join(homedir(), ".codex"))];
+    for (let dir = resolve(cwd);; dir = dirname(dir)) {
+        dirs.push(join(dir, ".codex"));
+        if (dirname(dir) === dir)
+            break;
+    }
+    return [...new Set(dirs)];
+}
+export function registeredAgentRoles(cwd, env = process.env) {
+    const names = new Set();
+    for (const dir of codexDirs(cwd, env)) {
+        for (const name of standaloneRoleNames(join(dir, "agents")))
+            names.add(name);
+        for (const name of configTableRoleNames(join(dir, "config.toml")))
+            names.add(name);
+    }
+    return names;
+}

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

@@ -4,6 +4,7 @@ import { parsePreToolUsePayload } from "./codex-hook.js";
 import { isFinalRunCompletionCandidate } from "./goal-status.js";
 import { ulwLoopAttemptEvidenceDir, ulwLoopDir, ulwLoopStateLockPath } from "./paths.js";
 import { readUlwLoopPlanSync } from "./plan-io.js";
+import { registeredAgentRoles } from "./registered-agent-roles.js";
 import { atomicWriteJson, isNonEmptyFile, readAdmissionBreaker, readCount, readCounts } from "./spawn-budget-io.js";
 import { spawnRoleDenial } from "./spawn-role-guard.js";
 import { isStateLockTimeout, withStateLockSync } from "./state-lock.js";
@@ -31,7 +32,7 @@ export function applySpawnGuards(payload, options = {}) {
     if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name))
         return "";
     if (resolveToolkitSurface() === "lazycodex") {
-        const reason = spawnRoleDenial(payload.tool_input);
+        const reason = spawnRoleDenial(payload.tool_input, () => registeredAgentRoles(payload.cwd));
         if (reason !== null)
             return deny(reason);
     }

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

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

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

@@ -14,9 +14,13 @@ export const LAZYCODEX_SPAWN_ROLES = new Set([
     "momus",
     "plan",
 ]);
-export function spawnRoleDenial(input) {
+export function spawnRoleDenial(input, registeredRoles = () => new Set()) {
     const role = typeof input === "object" && input !== null && "agent_type" in input ? input.agent_type : undefined;
     if (typeof role === "string" && LAZYCODEX_SPAWN_ROLES.has(role))
         return null;
-    return `LazyCodex requires an explicit registered agent_type: ${[...LAZYCODEX_SPAWN_ROLES].join(", ")}. Received ${JSON.stringify(role) ?? "no agent_type"}. Use the matching role and fork_turns: "none" (V2) or fork_context: false (V1), unless full history is deliberately required. The hook cannot see the tool schema; if agent_type is unavailable, stop and report incompatible role routing rather than spawning a generic agent. Describing a role in message does not select its TOML.`;
+    const registered = typeof role === "string" && role.trim() !== "" ? registeredRoles() : new Set();
+    if (typeof role === "string" && registered.has(role))
+        return null;
+    const known = [...new Set([...LAZYCODEX_SPAWN_ROLES, ...registered])];
+    return `LazyCodex requires an explicit registered agent_type: ${known.join(", ")}. Received ${JSON.stringify(role) ?? "no agent_type"}. Use the matching role and fork_turns: "none" (V2) or fork_context: false (V1), unless full history is deliberately required. The hook cannot see the tool schema; if agent_type is unavailable, stop and report incompatible role routing rather than spawning a generic agent. Describing a role in message does not select its TOML.`;
 }

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

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook user-prompt-submit --with-ultrawork",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.1.11) Checking Ulw-Loop Steering"
+						"statusMessage": "(OmO 5.1.13) 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.1.11) Recording Spawn Admission"
+						"statusMessage": "(OmO 5.1.13) 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.1.11) Enforcing Unlimited Ulw-Loop Budget"
+						"statusMessage": "(OmO 5.1.13) 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.1.11) Guarding Ulw-Loop Spawns"
+						"statusMessage": "(OmO 5.1.13) Guarding Ulw-Loop Spawns"
 					}
 				]
 			}
@@ -56,7 +56,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook stop",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.1.11) Checking Ulw-Loop Resume"
+						"statusMessage": "(OmO 5.1.13) 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.1.11",
+	"version": "5.1.13",
 	"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/src/registered-agent-roles.ts

@@ -0,0 +1,60 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+
+// Codex registers a role from a standalone `agents/*.toml` (keyed by its `name`, else the
+// file stem) or from an `[agents.<name>]` table in config.toml. It reads both under
+// CODEX_HOME and under a project's `.codex/`. Codex still validates the role itself (trust,
+// required fields); this only answers "does a role file declare this name".
+
+const NAME_LINE = /^\s*name\s*=\s*"([^"\n]+)"\s*(?:#.*)?$/m;
+const AGENT_TABLE = /^\s*\[agents\.(?:"([^"\n]+)"|([A-Za-z0-9_-]+))\]\s*(?:#.*)?$/gm;
+
+function readText(path: string): string | null {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return null;
+	}
+}
+
+function standaloneRoleNames(agentsDir: string): string[] {
+	let entries: string[];
+	try {
+		entries = readdirSync(agentsDir);
+	} catch {
+		return [];
+	}
+	const names: string[] = [];
+	for (const entry of entries) {
+		if (!entry.endsWith(".toml")) continue;
+		const text = readText(join(agentsDir, entry));
+		if (text === null) continue;
+		names.push(text.match(NAME_LINE)?.[1] ?? basename(entry, ".toml"));
+	}
+	return names;
+}
+
+function configTableRoleNames(configPath: string): string[] {
+	const text = readText(configPath);
+	if (text === null) return [];
+	return [...text.matchAll(AGENT_TABLE)].map((match) => match[1] ?? match[2] ?? "").filter(Boolean);
+}
+
+function codexDirs(cwd: string, env: NodeJS.ProcessEnv): string[] {
+	const dirs = [resolve(env["CODEX_HOME"]?.trim() || join(homedir(), ".codex"))];
+	for (let dir = resolve(cwd); ; dir = dirname(dir)) {
+		dirs.push(join(dir, ".codex"));
+		if (dirname(dir) === dir) break;
+	}
+	return [...new Set(dirs)];
+}
+
+export function registeredAgentRoles(cwd: string, env: NodeJS.ProcessEnv = process.env): ReadonlySet<string> {
+	const names = new Set<string>();
+	for (const dir of codexDirs(cwd, env)) {
+		for (const name of standaloneRoleNames(join(dir, "agents"))) names.add(name);
+		for (const name of configTableRoleNames(join(dir, "config.toml"))) names.add(name);
+	}
+	return names;
+}

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

@@ -6,6 +6,7 @@ import { parsePreToolUsePayload } from "./codex-hook.js";
 import { isFinalRunCompletionCandidate } from "./goal-status.js";
 import { ulwLoopAttemptEvidenceDir, ulwLoopDir, ulwLoopStateLockPath } from "./paths.js";
 import { readUlwLoopPlanSync } from "./plan-io.js";
+import { registeredAgentRoles } from "./registered-agent-roles.js";
 import { atomicWriteJson, isNonEmptyFile, readAdmissionBreaker, readCount, readCounts } from "./spawn-budget-io.js";
 import { spawnRoleDenial } from "./spawn-role-guard.js";
 import { isStateLockTimeout, type StateLockOptions, withStateLockSync } from "./state-lock.js";
@@ -47,7 +48,7 @@ export interface SpawnGuardOptions {
 export function applySpawnGuards(payload: PreToolUsePayload, options: SpawnGuardOptions = {}): string {
 	if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name)) return "";
 	if (resolveToolkitSurface() === "lazycodex") {
-		const reason = spawnRoleDenial(payload.tool_input);
+		const reason = spawnRoleDenial(payload.tool_input, () => registeredAgentRoles(payload.cwd));
 		if (reason !== null) return deny(reason);
 	}
 	return applySpawnBudgetGuards(payload, options);

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

@@ -15,8 +15,14 @@ export const LAZYCODEX_SPAWN_ROLES: ReadonlySet<string> = new Set([
 	"plan",
 ]);
 
-export function spawnRoleDenial(input: unknown): string | null {
+export function spawnRoleDenial(
+	input: unknown,
+	registeredRoles: () => ReadonlySet<string> = () => new Set(),
+): string | null {
 	const role = typeof input === "object" && input !== null && "agent_type" in input ? input.agent_type : undefined;
 	if (typeof role === "string" && LAZYCODEX_SPAWN_ROLES.has(role)) return null;
-	return `LazyCodex requires an explicit registered agent_type: ${[...LAZYCODEX_SPAWN_ROLES].join(", ")}. Received ${JSON.stringify(role) ?? "no agent_type"}. Use the matching role and fork_turns: "none" (V2) or fork_context: false (V1), unless full history is deliberately required. The hook cannot see the tool schema; if agent_type is unavailable, stop and report incompatible role routing rather than spawning a generic agent. Describing a role in message does not select its TOML.`;
+	const registered = typeof role === "string" && role.trim() !== "" ? registeredRoles() : new Set<string>();
+	if (typeof role === "string" && registered.has(role)) return null;
+	const known = [...new Set([...LAZYCODEX_SPAWN_ROLES, ...registered])];
+	return `LazyCodex requires an explicit registered agent_type: ${known.join(", ")}. Received ${JSON.stringify(role) ?? "no agent_type"}. Use the matching role and fork_turns: "none" (V2) or fork_context: false (V1), unless full history is deliberately required. The hook cannot see the tool schema; if agent_type is unavailable, stop and report incompatible role routing rather than spawning a generic agent. Describing a role in message does not select its TOML.`;
 }

package/packages/omo-codex/plugin/components/ulw-loop/test/spawn-role-matrix.test.ts

@@ -11,6 +11,7 @@ beforeEach(async () => {
 	cwd = await mkdtemp(join(tmpdir(), "spawn-role-matrix-"));
 	vi.stubEnv("OMO_AGENT_TOOLKIT_SURFACE", "lazycodex");
 	vi.stubEnv("PLUGIN_DATA", join(cwd, "data"));
+	vi.stubEnv("CODEX_HOME", join(cwd, "codex-home"));
 });
 afterEach(async () => {
 	vi.unstubAllEnvs();

package/packages/omo-codex/plugin/components/ulw-loop/test/spawn-role-registered.test.ts

@@ -0,0 +1,128 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { applySpawnGuards } from "../src/spawn-guard.js";
+
+let root: string;
+let project: string;
+let codexHome: string;
+
+beforeEach(async () => {
+	root = await mkdtemp(join(tmpdir(), "spawn-role-registered-"));
+	project = join(root, "project");
+	codexHome = join(root, "codex-home");
+	await mkdir(join(project, "src", "deep"), { recursive: true });
+	vi.stubEnv("OMO_AGENT_TOOLKIT_SURFACE", "lazycodex");
+	vi.stubEnv("PLUGIN_DATA", join(root, "data"));
+	vi.stubEnv("CODEX_HOME", codexHome);
+});
+afterEach(async () => {
+	vi.unstubAllEnvs();
+	await rm(root, { recursive: true, force: true });
+});
+
+async function role(dir: string, file: string, name?: string): Promise<void> {
+	await mkdir(dir, { recursive: true });
+	const header = name === undefined ? "" : `name = "${name}"\n`;
+	await writeFile(join(dir, file), `${header}description = "custom role"\ndeveloper_instructions = "Do the work."\n`);
+}
+
+function spawn(cwd: string, input: Record<string, unknown>): string {
+	return applySpawnGuards({
+		cwd,
+		hook_event_name: "PreToolUse",
+		model: "test",
+		permission_mode: "default",
+		session_id: "registered",
+		tool_name: "spawn_agent",
+		tool_input: {
+			task_name: "check",
+			message: "Perform the assigned read-only analysis.",
+			fork_turns: "none",
+			...input,
+		},
+		tool_use_id: "call",
+		transcript_path: null,
+		turn_id: "turn",
+	});
+}
+
+function denial(output: string): string | null {
+	if (output === "") return null;
+	const parsed: { hookSpecificOutput: { permissionDecision: string; permissionDecisionReason: string } } =
+		JSON.parse(output);
+	expect(parsed.hookSpecificOutput.permissionDecision).toBe("deny");
+	return parsed.hookSpecificOutput.permissionDecisionReason;
+}
+
+describe("#given custom roles registered outside the bundle", () => {
+	describe("#when a project registers them in .codex/agents", () => {
+		it("#then each registered role spawns, including from a nested working directory", async () => {
+			const agents = join(project, ".codex", "agents");
+			for (const name of ["cashflow_planner", "debt_planner", "wealth_planner", "finance_reviewer"])
+				await role(agents, `${name}.toml`, name);
+
+			for (const name of ["cashflow_planner", "debt_planner", "wealth_planner", "finance_reviewer"]) {
+				expect(denial(spawn(project, { agent_type: name }))).toBeNull();
+				expect(denial(spawn(join(project, "src", "deep"), { agent_type: name }))).toBeNull();
+			}
+		});
+
+		it("#then the role is keyed by its declared name, not the file name", async () => {
+			await role(join(project, ".codex", "agents"), "planner-file.toml", "wealth_planner");
+
+			expect(denial(spawn(project, { agent_type: "wealth_planner" }))).toBeNull();
+			expect(denial(spawn(project, { agent_type: "planner-file" }))).toContain('Received "planner-file"');
+		});
+
+		it("#then a role file without a name field registers under its file name", async () => {
+			await role(join(project, ".codex", "agents"), "cashflow_planner.toml");
+
+			expect(denial(spawn(project, { agent_type: "cashflow_planner" }))).toBeNull();
+		});
+	});
+
+	describe("#when they are registered under CODEX_HOME", () => {
+		it("#then a standalone agents/*.toml role and a config.toml [agents.<name>] role both spawn", async () => {
+			await role(join(codexHome, "agents"), "finance_reviewer.toml", "finance_reviewer");
+			await writeFile(
+				join(codexHome, "config.toml"),
+				'[agents]\nmax_threads = 4\n\n[agents.debt_planner]\nconfig_file = "./agents/debt.toml"\n',
+			);
+
+			expect(denial(spawn(project, { agent_type: "finance_reviewer" }))).toBeNull();
+			expect(denial(spawn(project, { agent_type: "debt_planner" }))).toBeNull();
+		});
+	});
+});
+
+describe("#given the guard's purpose of never spawning an unregistered or generic agent", () => {
+	it("#when the role has no role file anywhere #then it is still denied and the message lists the registered roles", async () => {
+		await role(join(project, ".codex", "agents"), "cashflow_planner.toml", "cashflow_planner");
+
+		const reason = denial(spawn(project, { agent_type: "worker" }));
+
+		expect(reason).toContain('Received "worker"');
+		expect(reason).toContain("cashflow_planner");
+		expect(reason).toContain("lazycodex-worker-medium");
+	});
+
+	it("#when agent_type is missing #then it is denied even with custom roles registered", async () => {
+		await role(join(project, ".codex", "agents"), "cashflow_planner.toml", "cashflow_planner");
+
+		expect(denial(spawn(project, {}))).toContain("Received no agent_type");
+	});
+
+	it("#when a role is registered only in a different project #then this project still denies it", async () => {
+		const other = join(root, "other-project");
+		await role(join(other, ".codex", "agents"), "cashflow_planner.toml", "cashflow_planner");
+
+		expect(denial(spawn(project, { agent_type: "cashflow_planner" }))).toContain('Received "cashflow_planner"');
+	});
+
+	it("#when the agents directory is unreadable or absent #then bundled roles still spawn", async () => {
+		expect(denial(spawn(project, { agent_type: "lazycodex-worker-medium" }))).toBeNull();
+		expect(denial(spawn(project, { agent_type: "explorer" }))).toBeNull();
+	});
+});