oh-my-opencode 4.5.12 → 4.6.0

package/packages/omo-codex/plugin/components/lsp/test/codex-hook-errors.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+
+import { runLspPostToolUseHook } from "../src/codex-hook.js";
+
+describe("codex PostToolUse diagnostics errors", () => {
+	it("#given diagnostics runner throws for a mutated file #when the hook evaluates diagnostics #then it returns blocked output with the thrown message", async () => {
+		// given
+		const output = await runLspPostToolUseHook(
+			{
+				tool_name: "write",
+				tool_input: { path: "src/missing.ts" },
+				tool_response: { ok: true },
+			},
+			async (filePath) => {
+				expect(filePath).toBe("src/missing.ts");
+				throw new Error("ENOENT: no such file or directory, open 'src/missing.ts'");
+			},
+		);
+
+		// when
+		const parsed: unknown = JSON.parse(output);
+		if (!isPostToolUseHookOutput(parsed)) throw new TypeError("Expected PostToolUse hook output");
+
+		// then
+		expect(parsed.reason).toBe(
+			"LSP diagnostics after editing src/missing.ts:\n\nENOENT: no such file or directory, open 'src/missing.ts'",
+		);
+		expect(parsed.hookSpecificOutput.additionalContext).toBe(parsed.reason);
+	});
+});
+
+interface PostToolUseHookOutput {
+	readonly decision: "block";
+	readonly reason: string;
+	readonly hookSpecificOutput: {
+		readonly hookEventName: "PostToolUse";
+		readonly additionalContext: string;
+	};
+}
+
+function isPostToolUseHookOutput(value: unknown): value is PostToolUseHookOutput {
+	if (!isRecord(value)) return false;
+	const hookSpecificOutput = value["hookSpecificOutput"];
+	return (
+		value["decision"] === "block" &&
+		typeof value["reason"] === "string" &&
+		isRecord(hookSpecificOutput) &&
+		hookSpecificOutput["hookEventName"] === "PostToolUse" &&
+		typeof hookSpecificOutput["additionalContext"] === "string"
+	);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/packages/omo-codex/plugin/components/lsp/test/package-smoke.test.ts

@@ -56,6 +56,7 @@ describe("plugin package metadata", () => {
 		const hooksJson = readHooksJson("hooks/hooks.json");
 		const mcpJson = readMcpJson(".mcp.json");
 		const cliSource = readFileSync("src/cli.ts", "utf8");
+		const codexHookCliSource = readFileSync("src/codex-hook-cli.ts", "utf8");
 		const codexHookSource = readFileSync("src/codex-hook.ts", "utf8");
 		const sourceFiles = readdirSync("src");
 
@@ -79,11 +80,12 @@ describe("plugin package metadata", () => {
 		expect(lspServer?.command).toBe("node");
 		expect(lspServer?.args).toEqual(["../../../../lsp-tools-mcp/dist/cli.js", "mcp"]);
 		expect(cliSource).not.toContain("./lazy-lsp-mcp.js");
-		expect(cliSource).not.toContain("@code-yeongyu/lsp-tools-mcp");
-		expect(cliSource).toContain("../../../../../lsp-tools-mcp/dist/cli.js");
-		expect(codexHookSource).not.toContain("@code-yeongyu/lsp-tools-mcp");
-		expect(codexHookSource).toContain("../../../../../lsp-tools-mcp/dist/lsp/manager.js");
-		expect(codexHookSource).toContain("../../../../../lsp-tools-mcp/dist/tools.js");
+		expect(cliSource).toContain("@code-yeongyu/lsp-tools-mcp/dist/cli.js");
+		expect(cliSource).not.toContain("../../../../../lsp-tools-mcp/dist/cli.js");
+		expect(codexHookCliSource).toContain("@code-yeongyu/lsp-tools-mcp/dist/lsp/manager.js");
+		expect(codexHookSource).toContain("@code-yeongyu/lsp-tools-mcp/dist/tools.js");
+		expect(codexHookCliSource).not.toContain("../../../../../lsp-tools-mcp/dist/lsp/manager.js");
+		expect(codexHookSource).not.toContain("../../../../../lsp-tools-mcp/dist/tools.js");
 		expect(sourceFiles.filter((name) => name.startsWith("lazy-mcp") || name === "lazy-lsp-mcp.ts")).toEqual([]);
 	});
 

package/packages/omo-codex/plugin/components/rules/README.md

@@ -43,7 +43,7 @@ Prefer strict TypeScript and keep runtime imports ESM-compatible.
 ## Install Locally
 
 ```bash
-bunx lazycodex install
+npx lazycodex-ai install
 ```
 
 The local installer builds the plugin and copies a clean cache entry to:

package/packages/omo-codex/plugin/components/rules/bundled-rules/windows-git-bash.md

@@ -0,0 +1,10 @@
+---
+description: Windows Git Bash guidance for Codex
+alwaysApply: true
+---
+
+On Windows native Codex sessions, prefer Git Bash for shell commands.
+
+Use `shell: "bash"` when `bash.exe` is on PATH. Otherwise use the absolute Git Bash path from `OMO_CODEX_GIT_BASH_PATH` or `C:\Program Files\Git\bin\bash.exe`.
+
+Use PowerShell only for Windows-native operations that need PowerShell.

package/packages/omo-codex/plugin/components/rules/test/package-smoke.test.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { readdirSync, readFileSync } from "node:fs";
 import { describe, expect, it } from "vitest";
 
 type PackageJson = {
@@ -51,6 +51,7 @@ describe("plugin package metadata", () => {
 		const pluginJson = readPluginJson(".codex-plugin/plugin.json");
 		const hooksJson = readHooksJson("hooks/hooks.json");
 		const cliSource = readFileSync("src/cli.ts", "utf8");
+		const bundledRules = readdirSync("bundled-rules").sort();
 
 		// when
 		const hookConfig = hooksJson.hooks;
@@ -69,6 +70,7 @@ describe("plugin package metadata", () => {
 		expect(packageJson.dependencies ?? {}).toEqual({ picomatch: "^4.0.3" });
 		expect(packageJson.bin["omo-rules"]).toBe("./dist/cli.js");
 		expect(packageJson.files).toContain("bundled-rules");
+		expect(bundledRules).toContain("windows-git-bash.md");
 		expect(pluginJson.hooks).toBe("./hooks/hooks.json");
 		expect(cliSource.startsWith("#!/usr/bin/env node")).toBe(true);
 		expect(commands).toEqual([

package/packages/omo-codex/plugin/components/rules/test/windows-git-bash-bundled-rule.test.ts

@@ -0,0 +1,97 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { runSessionStartHook, type CodexSessionStartInput } from "../src/codex-hook.js";
+import { findPluginBundledCandidates } from "../src/rules/finder.js";
+
+const WINDOWS_RULE_DESCRIPTION = "Windows Git Bash guidance for Codex";
+const WINDOWS_RULE_PATH = "bundled-rules/windows-git-bash.md";
+const WINDOWS_GUIDANCE = "On Windows native Codex sessions, prefer Git Bash for shell commands.";
+const BUNDLED_ONLY_ENV = {
+	CODEX_RULES_ENABLED_SOURCES: "plugin-bundled",
+};
+const PROJECT_AND_BUNDLED_ENV = {
+	CODEX_RULES_ENABLED_SOURCES: ".omo/rules,plugin-bundled",
+};
+const tempDirectories: string[] = [];
+let originalPluginRoot: string | undefined;
+
+afterEach(() => {
+	restoreEnv("PLUGIN_ROOT", originalPluginRoot);
+	for (const directory of tempDirectories.splice(0)) {
+		rmSync(directory, { recursive: true, force: true });
+	}
+});
+
+function makeProject(): { readonly root: string; readonly pluginData: string } {
+	originalPluginRoot = process.env["PLUGIN_ROOT"];
+	process.env["PLUGIN_ROOT"] = process.cwd();
+	const root = mkdtempSync(join(tmpdir(), "codex-rules-windows-git-bash-project-"));
+	const pluginData = mkdtempSync(join(tmpdir(), "codex-rules-windows-git-bash-data-"));
+	tempDirectories.push(root, pluginData);
+	writeFileSync(join(root, "package.json"), JSON.stringify({ name: "fixture" }));
+	return { root, pluginData };
+}
+
+function sessionStartInput(root: string): CodexSessionStartInput {
+	return {
+		session_id: "session-1",
+		transcript_path: null,
+		cwd: root,
+		hook_event_name: "SessionStart",
+		model: "gpt-5.5",
+		permission_mode: "default",
+		source: "startup",
+	};
+}
+
+function restoreEnv(name: string, value: string | undefined): void {
+	if (value === undefined) {
+		delete process.env[name];
+		return;
+	}
+	process.env[name] = value;
+}
+
+function occurrenceCount(value: string, search: string): number {
+	return value.split(search).length - 1;
+}
+
+describe("Windows Git Bash bundled rule", () => {
+	it("#given packaged bundled rules #when discovering plugin-bundled candidates #then Windows Git Bash rule is included", () => {
+		const candidates = findPluginBundledCandidates({ pluginRoot: process.cwd() });
+
+		expect(candidates.map((candidate) => candidate.relativePath)).toContain(WINDOWS_RULE_PATH);
+	});
+
+	it("#given bundled rules enabled #when SessionStart runs #then Windows Git Bash guidance is injected once", async () => {
+		const { root, pluginData } = makeProject();
+
+		const output = await runSessionStartHook(sessionStartInput(root), {
+			pluginDataRoot: pluginData,
+			env: BUNDLED_ONLY_ENV,
+		});
+
+		expect(occurrenceCount(output, WINDOWS_GUIDANCE)).toBe(1);
+	});
+
+	it("#given project rule with same description #when static rules load #then project guidance overrides bundled guidance", async () => {
+		const { root, pluginData } = makeProject();
+		const projectGuidance = "Project-specific Windows shell policy.";
+		mkdirSync(join(root, ".omo", "rules"), { recursive: true });
+		writeFileSync(
+			join(root, ".omo", "rules", "windows-git-bash.md"),
+			["---", `description: ${WINDOWS_RULE_DESCRIPTION}`, "alwaysApply: true", "---", "", projectGuidance].join("\n"),
+		);
+
+		const output = await runSessionStartHook(sessionStartInput(root), {
+			pluginDataRoot: pluginData,
+			env: PROJECT_AND_BUNDLED_ENV,
+		});
+
+		expect(output).toContain(projectGuidance);
+		expect(output).not.toContain(WINDOWS_GUIDANCE);
+	});
+});

package/packages/omo-codex/plugin/components/start-work-continuation/directive.md

@@ -18,10 +18,11 @@ You are mid-flight on a Prometheus work plan. The turn just ended without finish
 1. Read `{{PLAN_PATH}}` AND `{{LEDGER_PATH}}` first — ground truth for what remains and what evidence has already been recorded. The plan checkbox and the ledger are the only sources of truth; do not trust your own memory of prior turns.
 2. Pick the FIRST unchecked top-level checkbox in `## TODOs` or `## Final Verification Wave`. Ignore nested checkboxes under Acceptance Criteria / Evidence / Definition of Done.
 3. Follow the `start-work` skill in full. The skill is already loaded from your earlier turn — re-read its file at `packages/omo-codex/plugin/skills/start-work/SKILL.md` if you have lost context.
-4. Decompose the checkbox into atomic sub-tasks. Dispatch them in PARALLEL via `spawn_agent` calls in this same response unless a sub-task has a NAMED blocking dependency (input from another sub-task or shared file).
-5. Every sub-task message MUST include all 7 sections and name one Manual-QA channel with its exact tool and exact invocation (the literal `curl` / `send-keys` / `page.click` with concrete inputs and the binary PASS/FAIL observable), plus the applicable ultraqa adversarial classes, a captured artifact, and a cleanup receipt. Channels: HTTP call (`curl -i`); tmux (`send-keys` + `capture-pane`); browser use — use Chrome to drive the page, else download and use agent-browser (https://github.com/vercel-labs/agent-browser); computer use — OS-level GUI automation for a desktop app. Tests are the floor; the channel artifact plus probed adversarial classes are the ceiling. All are required.
-6. After verification of ALL sub-tasks under this checkbox: `apply_patch` the plan to change `- [ ]` → `- [x]`, re-read the plan to confirm the count decreased, append a `task-completed` line to the ledger, then continue.
-7. Do not start fresh on a sub-agent failure. Re-dispatch the same `task_name` with a fix-message: `FAILED: <exact error>` + `Diagnosis: <observation>` + `Fix: <instruction>`.
+4. Decompose the checkbox into atomic sub-tasks. Dispatch them in PARALLEL via `spawn_agent` calls in this same response unless a sub-task has a NAMED blocking dependency (input from another sub-task or shared file). Prefer `fork_turns: "none"` unless full history is truly required. Every dispatch sets `agent_type`; `model` + `reasoning_effort` alone creates a default agent, not the requested role.
+5. Every sub-task message MUST be self-contained and start with `TASK: <imperative assignment>`, then name `DELIVERABLE`, `SCOPE`, and `VERIFY`. State that it is an executable assignment, not a context handoff. It must include all 7 sections and name one Manual-QA channel with its exact tool and exact invocation (the literal `curl` / `send-keys` / `page.click` with concrete inputs and the binary PASS/FAIL observable), plus the applicable ultraqa adversarial classes, a captured artifact, and a cleanup receipt. Channels: HTTP call (`curl -i`); tmux (`send-keys` + `capture-pane`); browser use — use Chrome to drive the page, else download and use agent-browser (https://github.com/vercel-labs/agent-browser); computer use — OS-level GUI automation for a desktop app. Tests are the floor; the channel artifact plus probed adversarial classes are the ceiling. All are required.
+6. Use `wait_agent` for completion signals, but treat `wait_agent` as a mailbox signal, not proof of completion, content, or errors. After two waits with no substantive result, send one targeted followup: `TASK STILL ACTIVE: return <deliverable> or BLOCKED: <reason>`. If still silent or ack-only, record inconclusive, do not count it as pass/review approval, close if safe, and respawn a smaller `fork_turns: "none"` task with the missing deliverable.
+7. After verification of ALL sub-tasks under this checkbox: `apply_patch` the plan to change `- [ ]` → `- [x]`, re-read the plan to confirm the count decreased, append a `task-completed` line to the ledger, then continue.
+8. Do not start fresh on a sub-agent failure. Re-dispatch the same `task_name` with a fix-message: `FAILED: <exact error>` + `Diagnosis: <observation>` + `Fix: <instruction>`.
 
 # Hard constraints
 

package/packages/omo-codex/plugin/components/start-work-continuation/test/codex-hook.test.ts

@@ -49,6 +49,28 @@ describe("start-work Stop hook", () => {
 		expect(parsed.reason).toContain("- Your session id in boulder.json: `codex:sess_abc`");
 	});
 
+	it("#given active codex work #when continuation directive is emitted #then subagent guidance is reliable", () => {
+		// given
+		const fs = createMemoryFs({
+			[BOULDER_PATH]: createBoulderJson({
+				sessionIds: ["codex:sess_abc"],
+				status: "active",
+			}),
+			[PLAN_PATH]: ["# Plan", "", "## TODOs", "- [ ] First"].join("\n"),
+		});
+
+		// when
+		const output = runStopHook(createStopInput(), fs);
+
+		// then
+		const parsed = parseBlockOutput(output);
+		expect(parsed.reason).toMatch(/TASK:/);
+		expect(parsed.reason).toMatch(/fork_turns:\s*"none"/);
+		expect(parsed.reason).toMatch(/wait_agent.*signal, not proof/);
+		expect(parsed.reason).toMatch(/one targeted followup/);
+		expect(parsed.reason).toMatch(/respawn.*smaller/);
+	});
+
 	it("#given active work belongs to another harness #when hook runs #then returns empty output", () => {
 		// given
 		const fs = createMemoryFs({

package/packages/omo-codex/plugin/components/ultrawork/README.md

@@ -20,7 +20,7 @@ The directive is currently 10,951 chars / 231 lines and follows the GPT-5.5 prom
 ## Install (via this marketplace)
 
 ```bash
-bunx lazycodex install
+npx lazycodex-ai install
 ```
 
 The installer copies the plugin into `~/.codex/plugins/cache/sisyphuslabs/omo/0.1.0`, writes the stable Codex marketplace snapshot at `~/.codex/.tmp/marketplaces/sisyphuslabs/`, registers the `sisyphuslabs` marketplace from the `lazycodex` Git repository, enables `omo@sisyphuslabs` in `~/.codex/config.toml`, registers the `UserPromptSubmit` hook, and installs the bundled agent TOMLs into `~/.codex/agents/` (symlinks on Unix, copies on Windows). A `.installed-agents.json` manifest is written next to the bundled TOMLs' source root for clean uninstall tracking.
@@ -49,7 +49,7 @@ Expect `<ultrawork-mode>` ... directive body.
 
 ## Agent role smoke test
 
-Run `bunx omo install --platform=codex`, then inspect `~/.codex/agents/`. On Linux / macOS you should see symlinks; on Windows you should see file copies. Each TOML should declare a non-empty `name`, `description`, and `developer_instructions`.
+Run `npx lazycodex-ai install`, then inspect `~/.codex/agents/`. On Linux / macOS you should see symlinks; on Windows you should see file copies. Each TOML should declare a non-empty `name`, `description`, and `developer_instructions`.
 
 ## License
 

package/packages/omo-codex/plugin/components/ultrawork/agents/codex-ultrawork-reviewer.toml

@@ -8,6 +8,7 @@ developer_instructions = """You are the ultrawork verification reviewer.
 Review only. Do not implement.
 
 Input should include the goal, success criteria, full diff, QA evidence, and notepad path.
+If Codex delivers parent review context as inter-agent commentary, treat the latest parent message with goal/diff/evidence as your active review assignment, not passive context.
 
 Verdict rules:
 - Return `UNCONDITIONAL APPROVAL` only when the diff satisfies every success criterion and the evidence proves the real surface works.

package/packages/omo-codex/plugin/components/ultrawork/agents/librarian.toml

@@ -55,7 +55,7 @@ If the user names a version ("React 18", "Next.js 14", "v2.x"):
 
 ## Step 4 - targeted investigation
 - `webfetch(<specific-doc-page-from-sitemap>)`.
-- If a docs-indexer / library-index tool is available, query it for the specific topic. Otherwise rely on the sitemap-driven webfetch pages.
+- If `context7` is available, query it for the specific topic. Otherwise rely on the sitemap-driven webfetch pages.
 
 ## Skip Phase 0.5 when
 - TYPE B (implementation) - you're cloning the repo anyway.
@@ -70,7 +70,7 @@ If the user names a version ("React 18", "Next.js 14", "v2.x"):
 Run Phase 0.5 first, then in parallel:
 - `web_search` for current-year usage examples + best practices.
 - `webfetch` for the targeted doc pages identified by the sitemap.
-- `gh search code "<usage pattern>" --language <lang>` for real-world code samples.
+- `grep_app` for broad GitHub code search; fall back to `gh search code "<usage pattern>" --language <lang>`.
 
 ## TYPE B - IMPLEMENTATION REFERENCE
 Execute in sequence:
@@ -81,9 +81,9 @@ Execute in sequence:
 
 Parallel acceleration (4+ calls in one batch when independent):
 - Shallow clone.
-- `gh search code "<function-name>" --repo <owner>/<repo>`.
+- `grep_app` broad code search or `gh search code "<function-name>" --repo <owner>/<repo>`.
 - `gh api repos/<owner>/<repo>/commits/HEAD --jq '.sha'`.
-- Sitemap-targeted `webfetch` of the relevant docs page for the same API surface.
+- `context7` or sitemap-targeted `webfetch` of the relevant docs page for the same API surface.
 
 ## TYPE C - CONTEXT & HISTORY
 Execute in parallel (4+ calls):
@@ -100,7 +100,7 @@ For a specific issue / PR:
 ## TYPE D - COMPREHENSIVE
 Run Phase 0.5 first, then execute 6+ parallel calls:
 - 2 docs calls: `webfetch` targeted doc pages + (if available) a docs-indexer query.
-- 2 code-search calls: `gh search code` with varied queries (different angles).
+- 2 code-search calls: `grep_app` or `gh search code` with varied queries (different angles).
 - 1 source clone for deep inspection.
 - 1 issues/PRs query for context.
 
@@ -147,8 +147,9 @@ Never link to a branch name (`/blob/main/...`) - always pin to a SHA so the line
 - Sitemap -> `webfetch(<base>/sitemap.xml)` (fallbacks: `/sitemap-0.xml`, `/sitemap_index.xml`).
 - Read a specific page -> `webfetch(<page-url>)`.
 - Latest info -> `web_search("<query> <CURRENT_YEAR>")`.
-- Code search (fast, broad) -> `gh search code "<query>" --language <lang>` (org-wide or repo-scoped).
-- Code search (deep, repo-scoped) -> after cloning, `rg` / `ast_grep_search` over the clone.
+- Docs index -> `context7` when available; use sitemap-driven pages when it is not.
+- Code search (fast, broad) -> `grep_app` for web-scale GitHub search; `gh search code "<query>" --language <lang>` when you need GitHub CLI filters.
+- Code search (deep, repo-scoped) -> after cloning, `rg` / `ast_grep` over the clone.
 - Clone -> `gh repo clone <o>/<r> "${TMPDIR:-/tmp}/<name>" -- --depth 1`.
 - Issues / PRs -> `gh search issues|prs`, `gh issue|pr view <n> --comments`.
 - Release info -> `gh api repos/<o>/<r>/releases/latest`.

package/packages/omo-codex/plugin/components/ultrawork/agents/plan.toml

@@ -29,7 +29,8 @@ Never plan blind. Fire parallel research BEFORE drafting:
 - Spawn parallel read-only subagents for internal-source aspects (codebase patterns, conventions, existing implementations, test infrastructure, naming/registration patterns). One subagent per aspect.
 - Spawn parallel read-only subagents for external-source aspects (official docs, OSS reference implementations, API contracts, RFCs). One subagent per aspect.
 - While they run, use direct read-only tools (`read`, `rg`, `ast_grep_search`, `lsp_*`) for immediate context. Do not idle.
-- The role's own system prompt determines each subagent's output shape. Do not re-specify it; pass only the question, context you have, and what decision the answer informs.
+- The role's own system prompt determines each subagent's output shape. Do not re-specify it; pass only a self-contained `TASK: <question to answer now>`, the minimal context you have, `DELIVERABLE`, and what decision the answer informs.
+- Prefer `fork_turns: "none"` for research subagents unless full history is truly required. Treat `wait_agent` as a signal, not proof; if a child is silent or ack-only after one targeted followup, mark that lane inconclusive and answer from direct evidence or respawn smaller.
 
 Wait for context to converge before drafting. Rushed plans fail.
 

package/packages/omo-codex/plugin/components/ultrawork/directive.md

@@ -185,8 +185,31 @@ Until every success-criteria scenario PASSES with BOTH evidence pieces:
 
 Parallel-batch independent reads / searches / subagents within a step,
 but NEVER parallelise RED and GREEN of the same criterion.
-Do not use `list_agents` as a polling or status tool in long or high-context runs; it can replay large agent status and latest-message payloads.
-Track spawned agent names locally, use `wait_agent` for completion, send targeted followups only when needed, and `close_agent` after integrating each result.
+
+# Codex subagent reliability
+Every `spawn_agent` message is self-contained and starts with
+`TASK: <imperative assignment>`, then names `DELIVERABLE`, `SCOPE`, and
+`VERIFY`. State that it is an executable assignment, not a context
+handoff. Prefer `fork_turns: "none"` unless full history is truly
+required; paste only the context the child needs. Full-history forks can
+make the child continue old parent context instead of the delegated task.
+
+Do not use `list_agents` as a polling or status tool in long or
+high-context runs; it can replay large agent status and latest-message
+payloads. Track spawned agent names locally. 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. Use `wait_agent` for completion
+signals, but treat `wait_agent` as a mailbox signal, not proof of
+completion, content, or errors. A worker/reviewer counts only after you
+receive substantive output and verify its diff/evidence.
+After two waits with no substantive result, send one targeted followup:
+`TASK STILL ACTIVE: return <deliverable> or BLOCKED: <reason>`. If it is
+still silent or ack-only, record the result as inconclusive, do not
+count it as approval/pass, close it if safe, and respawn a smaller
+`fork_turns: "none"` task with the missing deliverable. Use targeted
+followups only when needed, and `close_agent` after integrating each
+result.
 
 # Verification gate (TRIGGERED, NOT OPTIONAL)
 
@@ -197,9 +220,12 @@ Trigger when ANY apply:
   anything the user called deep.
 
 Procedure (NON-NEGOTIABLE):
-1. Spawn agent_type `codex-ultrawork-reviewer` (or any `gpt-5.2`
-   xhigh reviewer if unavailable). Pass: goal, success-criteria,
-   scenario evidence, full diff, notepad path.
+1. Spawn `agent_type="codex-ultrawork-reviewer"` with
+   `fork_turns: "none"`. If unavailable, spawn `agent_type="worker"`
+   with a self-contained reviewer assignment and tight scope. `model` +
+   `reasoning_effort` alone creates a default agent, not a reviewer.
+   Pass: goal, success-criteria, scenario evidence, full diff, notepad
+   path.
 2. Treat the reviewer's verdict as binding. There is NO "false
    positive". Every concern is real. Do not argue. Do not minimise. Do
    not explain it away.

package/packages/omo-codex/plugin/components/ultrawork/test/codex-hook.test.ts

@@ -161,11 +161,34 @@ describe("codex ultrawork hook", () => {
 		const directive = parsed.hookSpecificOutput.additionalContext;
 		expect(directive).toMatch(/list_agents/);
 		expect(directive).toMatch(/polling or status tool/);
-		expect(directive).toMatch(/replay large agent status and latest-message payloads/);
+		expect(directive).toMatch(/replay large agent status and latest-message\s+payloads/);
 		expect(directive).toMatch(/Track spawned agent names locally/);
-		expect(directive).toMatch(/wait_agent.*completion/);
-		expect(directive).toMatch(/targeted followups only when needed/);
-		expect(directive).toMatch(/close_agent.*after integrating each result/);
+		expect(directive).toMatch(/wait_agent[\s\S]*completion/);
+		expect(directive).toMatch(/targeted\s+followups only when needed/);
+		expect(directive).toMatch(/close_agent[\s\S]*after integrating each\s+result/);
+		expect(directive).toMatch(/Plan and reviewer agents\s+may run for a long time/);
+		expect(directive).toMatch(/short wait_agent cycles/);
+		expect(directive).toMatch(/single long blocking wait/);
+	});
+
+	it("#given directive #when inspected #then hardens Codex subagent assignment ambiguity", () => {
+		// given
+		const payload = {
+			hook_event_name: "UserPromptSubmit",
+			prompt: "please ultrawork",
+		};
+
+		// when
+		const output = runUserPromptSubmitHook(payload);
+		const parsed = parseHookOutput(output);
+
+		// then
+		const directive = parsed.hookSpecificOutput.additionalContext;
+		expect(directive).toMatch(/TASK:/);
+		expect(directive).toMatch(/fork_turns:\s*"none"/);
+		expect(directive).toMatch(/wait_agent[\s\S]*signal, not\s+proof/);
+		expect(directive).toMatch(/one targeted followup/);
+		expect(directive).toMatch(/respawn.*smaller/);
 	});
 });
 

package/packages/omo-codex/plugin/components/ultrawork/test/package-smoke.test.ts

@@ -34,6 +34,31 @@ describe("codex ultrawork package metadata", () => {
 		expect(hookCommands).toContain(`node "${pluginRoot}/dist/cli.js" hook user-prompt-submit`);
 		expect(hookCommands).not.toContainEqual(expect.stringMatching(/\bpython3?\b|ultrawork-detector\.py/));
 	});
+
+	it("#given explorer guidance #when inspected #then names the packaged code-search MCP surface", () => {
+		// given
+		const explorer = readFileSync("agents/explorer.toml", "utf8");
+
+		// when
+		const guidance = explorer.toLowerCase();
+
+		// then
+		expect(guidance).toContain("ast_grep");
+		expect(guidance).toContain("structural");
+	});
+
+	it("#given librarian guidance #when inspected #then names the packaged research MCP surfaces", () => {
+		// given
+		const librarian = readFileSync("agents/librarian.toml", "utf8");
+
+		// when
+		const guidance = librarian.toLowerCase();
+
+		// then
+		expect(guidance).toContain("grep_app");
+		expect(guidance).toContain("context7");
+		expect(guidance).toContain("ast_grep");
+	});
 });
 
 function readJson(path: string): unknown {

package/packages/omo-codex/plugin/components/ulw-loop/README.md

@@ -47,7 +47,7 @@ npm pack --dry-run
 ## Local Codex Installation
 
 ```bash
-bunx lazycodex install
+npx lazycodex-ai install
 ```
 
 The installer builds and copies the plugin into `~/.codex/plugins/cache/sisyphuslabs/omo/0.1.0`, registers the `sisyphuslabs` marketplace from the `lazycodex` Git repository, installs runtime dependencies there, and enables: