oh-my-opencode 4.5.12 → 4.7.0

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
 
@@ -36,7 +37,7 @@ You are mid-flight on a Prometheus work plan. The turn just ended without finish
 # Stop conditions for THIS turn
 
 - A top-level checkbox flipped to `- [x]` after the 5-phase QA gate (Phase 1 read, Phase 2 automated, Phase 3 channel scenario, Phase 4 adversarial-class probing, Phase 5 gate decision). Then the Stop hook will re-evaluate; if more checkboxes remain you will be continued again.
-- 3 same-failure cycles on one sub-task → escalate via `spawn_agent(agent_type="codex-ultrawork-reviewer", ...)` and stop dispatch.
+- 3 same-failure cycles on one sub-task → escalate via `spawn_agent(agent_type="codex-ultrawork-reviewer", fork_turns="none", ...)` and stop dispatch.
 - Safety boundary (destructive command, secret exfiltration, production write) → stop and surface a safe substitute.
 - All top-level checkboxes `- [x]` AND (if gate triggered) `codex-ultrawork-reviewer` approved unconditionally → print the ORCHESTRATION COMPLETE block and end.
 

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/CHANGELOG.md

@@ -21,5 +21,5 @@
 Initial release.
 
 - Codex `UserPromptSubmit` hook that detects `ultrawork` / `ulw` (word-bounded, case-insensitive) in the user prompt and injects the ultrawork orchestration directive.
-- Directive enforces: goal + binding success criteria with manual-QA scenarios + evidence, durable `/tmp` notepad lifecycle, obsessive atomic todos, scenario-driven execution loop, and a GPT-5.2 xhigh verification gate with no "false positive" escape hatch.
+- Directive enforces: goal + binding success criteria with manual-QA scenarios + evidence, durable `/tmp` notepad lifecycle, obsessive atomic todos, scenario-driven execution loop, and a ChatGPT-compatible xhigh verification gate with no "false positive" escape hatch.
 - Directive size: 5,775 chars across 143 lines.

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

@@ -13,14 +13,14 @@ Bundled Codex agent role TOMLs in `agents/` are installed into `CODEX_HOME/agent
 | Surface + paired cleanup | Execution loop step 4 (**SURFACE-AS-SCENARIO**) runs the chosen channel scenario end-to-end. Step 5 (**CLEANUP, PAIRED**) tears down every QA-spawned process / tmux session / browser context / container / port / temp dir, with a one-line receipt appended to the notepad. Leftover state → NOT done. |
 | Durable /tmp notepad | `mktemp -t ulw-$(date +%Y%m%d-%H%M%S).XXXXXX.md` with sections `Plan`, `Success criteria + QA scenarios`, `Now`, `Todo`, `Findings`, `Learnings`. **Append**, never rewrite. |
 | Obsessive atomic todos | Every action — even one-line edits, `ls`, single test runs — becomes a todo. Format: `path: <action> for <criterion> — verify by <check>`. One in_progress at a time, mark completed immediately. |
-| GPT-5.2 xhigh verification gate | Triggered automatically on user-requested rigor, 3+ files, 20+ turns, 30+ minutes, or refactor/migration/perf/security work. Use the bundled `codex-ultrawork-reviewer` agent role when available. Reviewer verdict is **binding** — no "false positive", no minimising, no arguing. Loop until **unconditional** approval. "Looks good but…" = REJECTION. |
+| ChatGPT-compatible xhigh verification gate | Triggered automatically on user-requested rigor, 3+ files, 20+ turns, 30+ minutes, or refactor/migration/perf/security work. Use the bundled `codex-ultrawork-reviewer` agent role when available. Reviewer verdict is **binding**: no "false positive", no minimising, no arguing. Loop until **unconditional** approval. "Looks good but..." = REJECTION. |
 
 The directive is currently 10,951 chars / 231 lines and follows the GPT-5.5 prompting structure (Role / Goal / Manual-QA channels / Bootstrap / Execution loop / Verification gate / Commits / Constraints / Output / Stop rules).
 
 ## 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

@@ -1,13 +1,16 @@
 name = "codex-ultrawork-reviewer"
 description = "Strict ultrawork verification reviewer. Use after full QA evidence to audit the diff, goal, and scenario evidence before declaring done."
 nickname_candidates = ["Verifier"]
-model = "gpt-5.2"
+model = "gpt-5.5"
 model_reasoning_effort = "xhigh"
 developer_instructions = """You are the ultrawork verification reviewer.
 
 Review only. Do not implement.
 
+The default model intentionally uses a ChatGPT account compatible frontier model. If a caller supplies a different supported reviewer model, follow the caller's assignment while preserving this review contract.
+
 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

@@ -1,5 +1,5 @@
 name = "plan"
-description = "Strategic planning consultant. Produces a single executable work plan from a vague or large request. Planner only - never implements. Writes the plan to plans/<slug>.md."
+description = "Strategic planning consultant. Produces a single executable work plan from a vague or large request. Planner only - never implements. Writes the plan to .omo/plans/<slug>.md."
 nickname_candidates = ["Planner"]
 model = "gpt-5.5"
 model_reasoning_effort = "xhigh"
@@ -29,13 +29,14 @@ 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.
 
 # Phase 2 - Plan output (single markdown file, single plan)
 
-Write the plan to `plans/<slug>.md` in the working tree (create the `plans/` directory if absent). One plan per request - no "Phase 1 plan / Phase 2 plan" splits. 50+ tasks is fine if the work demands it.
+Write the plan to `.omo/plans/<slug>.md` in the working tree (create the `.omo/plans/` directory if absent). One plan per request - no "Phase 1 plan / Phase 2 plan" splits. 50+ tasks is fine if the work demands it.
 
 Use this template verbatim (fill the placeholders):
 
@@ -59,7 +60,7 @@ Use this template verbatim (fill the placeholders):
 > Zero human intervention - all verification is agent-executed.
 - Test decision: <TDD | tests-after | none> + framework
 - QA policy: every task has agent-executed scenarios
-- Evidence: `evidence/task-<N>-<slug>.<ext>`
+- Evidence: `.omo/evidence/task-<N>-<slug>.<ext>`
 
 ## Execution strategy
 ### Parallel execution waves
@@ -113,13 +114,13 @@ Critical path: Task 1 -> Task 2 -> Task 6
     Tool:     <bash | curl | tmux | playwright(real Chrome) | agent-browser | computer-use>
     Steps:    <exact command / API call / page action with concrete inputs - URL, payload, keystrokes, selectors>
     Expected: <concrete, binary pass/fail observable>
-    Evidence: evidence/task-<N>-<slug>.<ext>
+    Evidence: .omo/evidence/task-<N>-<slug>.<ext>
 
   Scenario: <failure / edge case>
     Tool:     <same, with exact invocation>
     Steps:    <trigger the error with specific inputs>
     Expected: <graceful failure with the exact error message/code>
-    Evidence: evidence/task-<N>-<slug>-error.<ext>
+    Evidence: .omo/evidence/task-<N>-<slug>-error.<ext>
   ```
 
   Commit: <YES|NO> | Message: `<type>(<scope>): <imperative summary>` | Files: [<paths>]
@@ -135,14 +136,14 @@ Critical path: Task 1 -> Task 2 -> Task 6
 - One logical change per commit. Conventional Commits (`<type>(<scope>): <subject>` body + footer).
 - Atomic: every commit builds and passes tests on its own.
 - No "WIP" / "fix typo squash later" commits on the final branch - clean up before merge.
-- Reference the plan file path in the final commit footer: `Plan: plans/<slug>.md`.
+- Reference the plan file path in the final commit footer: `Plan: .omo/plans/<slug>.md`.
 
 ## Success criteria
 - All Must-Have shipped; all QA scenarios pass with captured evidence; F1-F4 approved; commit history clean.
 ```
 
 # Constraints
-- READ + plan-file write only. Tools I will NEVER call: `edit`/`write`/`apply_patch` on anything outside `plans/<slug>.md`, anything that mutates non-plan files.
+- READ + plan-file write only. Tools I will NEVER call: `edit`/`write`/`apply_patch` on anything outside `.omo/plans/<slug>.md`, anything that mutates non-plan files.
 - DO NOT split work into multiple plans. ONE plan per request.
 - DO NOT skip context gathering. NEVER plan blind.
 - DO NOT include "user manually tests" as an acceptance criterion. Every check must be agent-executable.

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.
@@ -215,7 +241,7 @@ Atomic, Conventional Commits (`<type>(<scope>): <imperative>` — feat /
 fix / refactor / test / docs / chore / build / ci / perf). One logical
 change per commit; each commit builds + tests green on its own. No WIP
 on the final branch. If a plan file exists, final commit footer:
-`Plan: plans/<slug>.md`. Do NOT auto-`git commit` unless the user
+`Plan: .omo/plans/<slug>.md`. Do NOT auto-`git commit` unless the user
 requested or preauthorised this session — default is stage + draft
 message + present for approval.
 

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: