oh-my-opencode 4.13.0 → 4.14.1

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

@@ -1,4 +1,5 @@
 import { parseUlwLoopSteeringDirective, steerUlwLoop } from "./steering.js";
+import { buildUltraworkDirectiveOutput } from "./ultrawork-directive.js";
 const CREATE_GOAL_TOOL_NAME = "create_goal";
 const CREATE_GOAL_PAYLOAD_WARNING = "Use create_goal with objective only. Omit token_budget so the goal stays unlimited, and put lifecycle status changes on update_goal.";
 export function parseUserPromptSubmitPayload(raw) {
@@ -27,13 +28,16 @@ export function parsePreToolUsePayload(raw) {
         return null;
     }
 }
-export async function applyUserPromptUlwLoopSteering(payload) {
+export async function applyUserPromptUlwLoopSteering(payload, options = {}) {
     try {
         if (payload.hook_event_name !== "UserPromptSubmit")
             return "";
         const proposal = parseUlwLoopSteeringDirective(payload.prompt);
-        if (proposal === null)
-            return "";
+        if (proposal === null) {
+            if (hasSteeringDirectiveMarker(payload.prompt))
+                return "";
+            return options.includeUltraworkDirective ? buildUltraworkDirectiveOutput(payload) : "";
+        }
         const result = await steerUlwLoop(payload.cwd, proposal, payloadScope(payload));
         if (!result.accepted)
             return "";
@@ -50,6 +54,9 @@ export async function applyUserPromptUlwLoopSteering(payload) {
         return "";
     }
 }
+function hasSteeringDirectiveMarker(prompt) {
+    return /(?:^|\s)(?:OMO_ULW_LOOP_STEER|omo\.ulw-loop\.steer|omo ulw-loop steer):/u.test(prompt);
+}
 function payloadScope(payload) {
     return { sessionId: payload.session_id };
 }
@@ -70,12 +77,12 @@ export function applyPreToolUseGoalBudgetGuard(payload) {
     };
     return `${JSON.stringify(output)}\n`;
 }
-export async function runUlwLoopHookCli(stdin, stdout) {
+export async function runUlwLoopHookCli(stdin, stdout, options = {}) {
     try {
         const payload = parseUserPromptSubmitPayload(await readAll(stdin));
         if (payload === null)
             return;
-        const output = await applyUserPromptUlwLoopSteering(payload);
+        const output = await applyUserPromptUlwLoopSteering(payload, options);
         if (output.length > 0)
             stdout.write(output);
     }
@@ -107,7 +114,10 @@ function isUserPromptSubmitPayload(value) {
         typeof value["cwd"] === "string" &&
         typeof value["prompt"] === "string" &&
         typeof value["session_id"] === "string" &&
-        ["model", "permission_mode", "transcript_path", "turn_id"].every((key) => optionalString(value[key])));
+        ["model", "permission_mode", "turn_id"].every((key) => optionalString(value[key])) &&
+        (value["transcript_path"] === undefined ||
+            value["transcript_path"] === null ||
+            typeof value["transcript_path"] === "string"));
 }
 function isPreToolUsePayload(value) {
     if (!isRecord(value))

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

@@ -0,0 +1,5 @@
+export interface UltraworkDirectiveInput {
+    readonly prompt: string;
+    readonly transcript_path?: string | null;
+}
+export declare function buildUltraworkDirectiveOutput(input: UltraworkDirectiveInput): string;

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

@@ -0,0 +1,104 @@
+import { readFileSync } from "node:fs";
+const ULTRAWORK_DIRECTIVE = readFileSync(new URL("../directive.md", import.meta.url), "utf8");
+const ULTRAWORK_CURRENT_PROMPT_PATTERN = /(?:ultrawork|ulw)/i;
+const ULTRAWORK_DIRECTIVE_MARKER = "<ultrawork-mode>";
+const TRANSCRIPT_SEARCH_BYTES = 512_000;
+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 buildUltraworkDirectiveOutput(input) {
+    if (isContextPressureRecoveryPrompt(input.prompt))
+        return "";
+    if (hasUltraworkDirectiveAlreadyInTranscript(input.transcript_path))
+        return "";
+    if (isContextPressureTranscript(input.transcript_path))
+        return "";
+    return isUltraworkPrompt(input.prompt) ? formatAdditionalContextOutput(ULTRAWORK_DIRECTIVE) : "";
+}
+function hasUltraworkDirectiveAlreadyInTranscript(transcriptPath) {
+    if (transcriptPath === undefined || transcriptPath === null)
+        return false;
+    try {
+        const rawTranscript = readTranscriptTail(transcriptPath);
+        for (const line of rawTranscript.split(/\r?\n/)) {
+            const parsed = parseJsonLine(line);
+            if (!isRecord(parsed))
+                continue;
+            const hookSpecificOutput = parsed["hookSpecificOutput"];
+            if (!isRecord(hookSpecificOutput))
+                continue;
+            if (hookSpecificOutput["hookEventName"] !== "UserPromptSubmit")
+                continue;
+            if (typeof hookSpecificOutput["additionalContext"] === "string" &&
+                hookSpecificOutput["additionalContext"].includes(ULTRAWORK_DIRECTIVE_MARKER)) {
+                return true;
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return false;
+        throw error;
+    }
+    return false;
+}
+function readTranscriptTail(transcriptPath) {
+    const rawTranscript = readFileSync(transcriptPath);
+    return rawTranscript.subarray(Math.max(0, rawTranscript.byteLength - TRANSCRIPT_SEARCH_BYTES)).toString("utf8");
+}
+function isUltraworkPrompt(prompt) {
+    return ULTRAWORK_CURRENT_PROMPT_PATTERN.test(prompt);
+}
+function isContextPressureRecoveryPrompt(prompt) {
+    const normalizedPrompt = prompt.toLowerCase();
+    return CONTEXT_PRESSURE_MARKERS.some((marker) => normalizedPrompt.includes(marker));
+}
+function isContextPressureTranscript(transcriptPath) {
+    if (transcriptPath === undefined || transcriptPath === null)
+        return false;
+    try {
+        return isContextPressureRecoveryPrompt(readTranscriptTail(transcriptPath));
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return false;
+        throw error;
+    }
+}
+function formatAdditionalContextOutput(additionalContext) {
+    const normalizedContext = normalizeAdditionalContext(additionalContext);
+    if (normalizedContext.length === 0)
+        return "";
+    const output = {
+        hookSpecificOutput: {
+            hookEventName: "UserPromptSubmit",
+            additionalContext: normalizedContext,
+        },
+    };
+    return `${JSON.stringify(output)}\n`;
+}
+function normalizeAdditionalContext(additionalContext) {
+    return additionalContext.replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim();
+}
+function parseJsonLine(line) {
+    if (line.trim().length === 0)
+        return null;
+    try {
+        const parsed = JSON.parse(line);
+        return parsed;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return null;
+        throw error;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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

@@ -5,7 +5,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook user-prompt-submit",
+						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook user-prompt-submit --with-ultrawork",
 						"timeout": 10,
 						"statusMessage": "(OmO) Checking Ulw-Loop Steering"
 					}

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

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-ulw-loop",
-	"version": "4.13.0",
+	"version": "4.14.1",
 	"description": "Codex plugin: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",
@@ -23,10 +23,13 @@
 		"typescript"
 	],
 	"bin": {
-		"omo-ulw-loop": "./dist/cli.js"
+		"omo-ulw-loop": "./dist/cli.js",
+		"ulw": "./dist/cli.js",
+		"ulw-loop": "./dist/cli.js"
 	},
 	"files": [
 		"dist",
+		"directive.md",
 		"hooks",
 		"skills",
 		"LICENSE",

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

@@ -20,7 +20,7 @@ This skill is intentionally compact. The full workflow lives in `references/full
 ## Non-Negotiables
 
 - Use the ulw-loop CLI state under `.omo/ulw-loop`; do not hand-edit goal state.
-- After any compaction or context loss, re-read brief + goals + ledger FIRST (`omo sparkshell cat .omo/ulw-loop/ledger.jsonl` or read directly) plus `omo ulw-loop status --json`, then resume; never re-plan from scratch.
+- 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 (tmux, HTTP, browser, computer-use) or, for CLI- or data-shaped criteria, an auxiliary surface (CLI stdout, DB diff, parsed config dump).
 - Record evidence through the CLI only after cleanup receipts are available.

package/packages/omo-codex/plugin/components/ulw-loop/skills/ulw-loop/references/full-workflow.md

@@ -6,12 +6,12 @@ metadata:
 ---
 
 ## Role
-Expert goal orchestration agent. You conduct; right-sized parallel subagents play. Plan multi-goal work that survives across turns and sessions, fan independent work out to workers, QA every result yourself, record only proven evidence.
+Expert goal orchestration agent. You conduct; right-sized subagents play. Plan durable multi-goal work, fan independent work out, QA every result yourself, record only proven evidence.
 Use GPT-5.x style: outcome-first, evidence-bound, atomic decisions, no nested branching prose.
 
 ## Goal
 Deliver every goal in `.omo/ulw-loop/goals.json` end-to-end.
-Prove EVERY success criterion with captured observable evidence from a real-usage scenario you actually ran (HTTP call / tmux / browser use / computer use — see the Manual-QA channels below).
+Prove EVERY success criterion with captured observable evidence from a real-usage scenario you ran (HTTP / tmux / browser / computer-use below).
 TESTS ALONE NEVER PROVE DONE. A green test suite is supporting evidence, not completion proof.
 Audit each pass, fail, block, steering change, and checkpoint in `.omo/ulw-loop/ledger.jsonl`.
 
@@ -20,8 +20,15 @@ Run each criterion's real-surface proof yourself through the channel that faithf
 
 1. **HTTP call** — hit the live endpoint with `curl -i` (or a Playwright APIRequestContext); capture status line + headers + body.
 2. **tmux** — `tmux new-session -d -s ulw-qa-<criterion>`, drive with `send-keys`, dump via `tmux capture-pane -pS -E -`; transcript is the artifact.
-3. **Browser use** — use Chrome to drive the REAL page; if Chrome is not available, download and use agent-browser (https://github.com/vercel-labs/agent-browser). Capture action log + screenshot path. Never downgrade to a non-browser surface for a browser-facing criterion.
-4. **Computer use** — when the surface is a desktop/GUI app rather than a page, drive it via OS-level automation (a computer-use agent, AppleScript, xdotool, etc.) against the running app; capture action log + screenshot. Use this for any non-browser GUI criterion.
+3. **Browser use** — in Codex, use `browser:control-in-app-browser` first when available and the scenario does not need an authenticated or persistent user browser profile. Otherwise use Chrome to drive the REAL page; if unavailable, use agent-browser. Capture action log + screenshot path. Never downgrade a browser-facing criterion.
+4. **Computer use** — for desktop/GUI apps, drive the running app via OS automation (computer-use, AppleScript, xdotool, etc.); capture action log + screenshot.
+
+For TUI visual QA, pair the tmux transcript with a browser-rendered terminal
+screenshot. In this repo run `node script/qa/web-terminal-visual-qa.mjs
+--from-file <capture.txt> --evidence-dir <dir>` and record `terminal.png`,
+`terminal.html`, `terminal.txt`, and `metadata.json` as the visual evidence
+bundle. This is mandatory when a PR or review needs to inspect the terminal
+screen, not just the text.
 
 Auxiliary surfaces (CLI stdout / DB state diff / parsed config dump) are first-class evidence for CLI- or data-shaped criteria; use a channel scenario when the behavior is user-facing. `--dry-run`, printing the command, "should respond", and "looks correct" never count.
 
@@ -42,7 +49,7 @@ Size each worker to the task. Put the intended role, rigor level, and specialty
 
 For reviewer work, use a self-contained reviewer assignment, tight scope, and explicit verification in `message`. Never spawn a context-only child for review.
 
-Every worker message MUST carry: goal + exact files in scope; the PIN + failing-first proof required before production code (Per-Criterion Cycle step 3); constraints + project rules; the verification commands; the ONE Manual-QA channel and the exact evidence artifact to capture; for git-tracked edits, require `git-master` plus repository-wide and touched-path commit history inspection before commit. Workers have NO interview context — be exhaustive, and forward accumulated learnings to every next worker.
+Every worker message MUST carry: goal + exact files in scope; the PIN + failing-first proof before production code; constraints + project rules; verification commands; the ONE Manual-QA channel and exact artifact; for git-tracked edits, require `git-master` plus repo and touched-path commit history before commit. Workers have NO interview context — be exhaustive, and forward learnings.
 
 Codex subagent reliability:
 - Start every `multi_agent_v1.spawn_agent` message with `TASK: <imperative assignment>`, then name `DELIVERABLE`, `SCOPE`, and `VERIFY`. State that it is an executable assignment, not a context handoff.
@@ -58,7 +65,7 @@ Codex subagent reliability:
 - `.omo/ulw-loop/goals.json`: goals with embedded `successCriteria` per goal.
 - `.omo/ulw-loop/ledger.jsonl`: append-only audit trail.
 - Read artifacts before resuming, steering, or checkpointing.
-- After any compaction or context loss, re-read brief + goals + ledger FIRST via `omo sparkshell cat .omo/ulw-loop/ledger.jsonl` (or read the paths directly), then `omo ulw-loop status --json`, before any further action. Recover state from these artifacts; never re-plan from scratch or repeat completed work (re-hypothesizing inside a research goal is not a re-plan).
+- After compaction or context loss, re-read brief + goals + ledger FIRST, then `omo ulw-loop status --json`. Recover from artifacts; never re-plan from scratch or repeat completed work.
 - Never invent state outside `.omo/ulw-loop` artifacts or `omo ulw-loop status --json`.
 
 ## Bootstrap
@@ -116,14 +123,15 @@ only when deliberately overwriting completed evidence.
 Write state through the CLI path. Do not hand-edit state files.
 
 ### 2. Refine success criteria + a Prometheus-grade QA and parallelism plan per goal
-Gather context BEFORE planning — fire parallel `explorer` / `librarian` workers plus your own read-only tools; never plan blind.
+Gather context BEFORE planning with parallel `explorer` / `librarian` workers plus your own read-only tools.
 First survey available skills: read every loosely-relevant skill's description, deliberately choose which this work uses, and prefer applying genuinely-relevant skills over working raw.
 Then run tier triage per goal — rigor (LIGHT/HEAVY below) and shape (`delivery` default, or `research` when the deliverable is a cited answer, not an artifact) — and record both in an `annotate_ledger` steering entry. Default is LIGHT — a narrow change inside existing layers. Take HEAVY only on a fact you can point to: a new module / abstraction / domain model; auth, security, or session; an external integration; a DB schema or migration; concurrency, transaction boundaries, or cache invalidation; a cross-domain refactor; or the user signaled care or demanded review. When unsure, take HEAVY; upgrade the moment a HEAVY fact surfaces, never downgrade mid-run.
 HEAVY goals: spawn the `plan` agent with the gathered context, follow its wave ordering and parallel grouping exactly, and run the verification it specifies; carry 3+ successCriteria covering happy path, edge, regression, and adversarial risk. LIGHT goals: plan directly; carry 1-2 successCriteria (happy path + the riskiest edge) with one real-surface proof of the deliverable.
-Research-shape goals change the cycle: BEFORE each investigation, read this goal's prior ledger findings and open hypotheses, then extend them — never re-investigate an answered question (the ledger is your research notebook). Record findings via `annotate_ledger` with their source (`file:line`, command output, doc URL) as `--evidence`. Track hypotheses as `HYPOTHESIS[id]: <claim> | status: open`, flipped to `confirmed`/`refuted` only on an observed source. A research criterion passes on a cited answer — skip QA-channel, cleanup, and commit, but keep source-observability (never "looks correct"). Keep hypotheses inside the user's stated question; a scope-widening one is an `add_subgoal` proposal you surface, never silent creep. For a `research`-shape goal you MAY load `ultraresearch` without hesitation — otherwise explicit-request-only, a research-shape goal IS that explicit demand. Research-only: never for a `delivery` goal. It composes with the librarian routing above — `ultraresearch` for saturation (many parallel sources, recursive expansion), a single `librarian` for one lookup.
-For each criterion set, concretely and upfront: `id`, `scenario` (the exact tool — curl / tmux / playwright / computer-use — plus steps with specific inputs and a binary pass/fail), `expectedEvidence` (the artifact path, e.g. `.omo/ulw-loop/evidence/<goal>-<criterion>.<ext>`), adversarial classes, stop condition, and the Manual-QA channel that exercises it. Vague QA ("verify it works") is a rejected criterion — revise it before execution.
+Research-shape goals change the cycle: BEFORE each investigation, read this goal's prior ledger findings and open hypotheses, then extend them — never re-investigate an answered question (the ledger is your research notebook). Record findings via `annotate_ledger` with their source (`file:line`, command output, doc URL) as `--evidence`. Track hypotheses as `HYPOTHESIS[id]: <claim> | status: open`, flipped to `confirmed`/`refuted` only on an observed source. A research criterion passes on a cited answer — skip QA-channel, cleanup, and commit, but keep source-observability (never "looks correct"). Keep hypotheses inside the user's stated question; a scope-widening one is an `add_subgoal` proposal you surface, never silent creep. For a `research`-shape goal you MAY load `ulw-research` (legacy alias: `ultraresearch`) without hesitation — otherwise explicit-request-only, a research-shape goal IS that explicit demand. Research-only: never for a `delivery` goal. It composes with the librarian routing above — `ulw-research` for saturation (many parallel sources, recursive expansion), a single `librarian` for one lookup.
+For each criterion, define upfront: `id`, exact `scenario` (tool + inputs + binary pass/fail), `expectedEvidence` artifact path, adversarial classes, stop condition, and Manual-QA channel. Vague QA ("verify it works") is a rejected criterion — revise it before execution.
+For optimization work, capture baseline speed before changes plus behavior/regression proof. Every attempt records speed, behavior/regression, and the keep/revert/iterate decision.
 A criterion's adversarial classes are the ultraqa classes a fact about the change triggers: malformed input, prompt injection, cancel/resume, stale state, dirty worktree, hung or long commands, flaky tests, misleading success output, repeated interruptions. Record untriggered classes as not-applicable in one line.
-Use evidence verbs from the channel table (tmux transcript, curl status+body, browser screenshot, computer-use action log, CLI stdout, DB diff, parsed config dump) — not vibes.
+Use channel-table evidence verbs (tmux transcript, curl status+body, screenshot, action log, CLI stdout, DB diff, parsed config dump) — not vibes.
 
 **Plan for maximum parallelism (HEAVY goals).** Decompose each goal's criteria into atomic tasks (Implementation + its Test = ONE task, never split) and group them into dependency waves. Target 5–8 tasks per wave; <3 per wave (except the final wave) means under-splitting — extract shared prerequisites into Wave 1. For each task record its wave, what it blocks, what blocks it, the worker tier from the Delegation table, and its QA scenario + evidence path. Build a dependency matrix (Task | Depends on | Blocks | Can parallelize with) and name the critical path. Anything not on a real dependency edge MUST share a wave and dispatch together.
 Revise any criterion that lacks observable `expectedEvidence` or a named channel before execution.
@@ -186,9 +194,9 @@ omo ulw-loop checkpoint --goal-id <id> --status complete --evidence "<e2e eviden
 `--quality-gate-json` shape:
 ```json
 {
-  "codeReview":{"by":"lazycodex-code-reviewer","recommendation":"APPROVE","codeQualityStatus":"CLEAR","reportPath":"packages/omo-codex/plugin/components/ulw-loop/test/fixtures/artifacts/code-review.md","evidence":"Diff review passed.","blockers":[]},
-  "manualQa":{"by":"lazycodex-qa-executor","status":"passed","evidence":"CLI and data surfaces passed.","surfaceEvidence":[{"id":"surface-cli-pass","criterionRef":"C1","surface":"cli","invocation":"omo ulw-loop checkpoint --quality-gate-json sample-quality-gate.json --json","verdict":"passed","artifactRefs":["artifact-cli-pass"]},{"id":"surface-data-pass","criterionRef":"C2","surface":"data","invocation":"diff -u before-ledger.json after-ledger.json","verdict":"passed","artifactRefs":["artifact-data-diff"]}],"adversarialCases":[{"id":"adv-malformed-input","criterionRef":"C3","scenario":"malformed gate input omits manual QA evidence","expectedBehavior":"validator rejects ULW_LOOP_QUALITY_GATE_INVALID","verdict":"passed","artifactRefs":["artifact-cli-reject"]}],"artifactRefs":[{"id":"artifact-cli-pass","kind":"cli-transcript","description":"CLI pass artifact.","path":"packages/omo-codex/plugin/components/ulw-loop/test/fixtures/artifacts/cli-pass.txt"},{"id":"artifact-cli-reject","kind":"log","description":"Reject log artifact.","path":"packages/omo-codex/plugin/components/ulw-loop/test/fixtures/artifacts/rejection.txt"},{"id":"artifact-data-diff","kind":"data-diff","description":"Data diff artifact.","path":"packages/omo-codex/plugin/components/ulw-loop/test/fixtures/artifacts/data-diff.txt"}]},
-  "gateReview":{"by":"lazycodex-gate-reviewer","recommendation":"APPROVE","reportPath":"packages/omo-codex/plugin/components/ulw-loop/test/fixtures/artifacts/gate-review.md","evidence":"Gate review passed.","blockers":[]},
+  "codeReview":{"by":"lazycodex-code-reviewer","recommendation":"APPROVE","codeQualityStatus":"CLEAR","reportPath":"test/fixtures/artifacts/code-review.md","evidence":"Diff review passed.","blockers":[]},
+  "manualQa":{"by":"lazycodex-qa-executor","status":"passed","evidence":"CLI and data surfaces passed.","surfaceEvidence":[{"id":"surface-cli-pass","criterionRef":"C1","surface":"cli","invocation":"omo ulw-loop checkpoint --quality-gate-json sample-quality-gate.json --json","verdict":"passed","artifactRefs":["artifact-cli-pass"]},{"id":"surface-data-pass","criterionRef":"C2","surface":"data","invocation":"diff -u before-ledger.json after-ledger.json","verdict":"passed","artifactRefs":["artifact-data-diff"]}],"adversarialCases":[{"id":"adv-malformed-input","criterionRef":"C3","scenario":"malformed gate input omits manual QA evidence","expectedBehavior":"validator rejects ULW_LOOP_QUALITY_GATE_INVALID","verdict":"passed","artifactRefs":["artifact-cli-reject"]}],"artifactRefs":[{"id":"artifact-cli-pass","kind":"cli-transcript","description":"CLI pass artifact.","path":"test/fixtures/artifacts/cli-pass.txt"},{"id":"artifact-cli-reject","kind":"log","description":"Reject log artifact.","path":"test/fixtures/artifacts/rejection.txt"},{"id":"artifact-data-diff","kind":"data-diff","description":"Data diff artifact.","path":"test/fixtures/artifacts/data-diff.txt"}]},
+  "gateReview":{"by":"lazycodex-gate-reviewer","recommendation":"APPROVE","reportPath":"test/fixtures/artifacts/gate-review.md","evidence":"Gate review passed.","blockers":[]},
   "iteration":{"fullRerun":true,"status":"passed","rerunCommands":["bunx vitest run packages/omo-codex/plugin/components/ulw-loop/test/quality-gate-doc.test.ts"],"evidence":"Focused rerun passed."},
   "criteriaCoverage":{"totalCriteria":3,"passCount":3,"originalIntent":"User wanted artifact-backed completion.","desiredOutcome":"Behavior ships with review and QA evidence.","userOutcomeReview":"Result matches brief and goals.","adversarialClassesCovered":["malformed_input","stale_state"]}
 }
@@ -220,7 +228,7 @@ Structured prompt directives accepted: `OMO_ULW_LOOP_STEER: { ... }`, `omo.ulw-l
 6. Treat `.omo/ulw-loop/ledger.jsonl` as the durable audit trail; checkpoint after every success or failure.
 7. Per-story Codex goal mode is opt-in only with `--codex-goal-mode per-story`; default is aggregate.
 8. Structured steering directives mutate state through validation; normal prose does not.
-9. Evidence MUST be observable from the real surface: tmux transcript, curl status+body, browser/Playwright assertion, CLI stdout, DB state diff, parsed config dump.
+9. Evidence MUST be observable from the real surface: tmux transcript, curl status+body, Browser plugin action result or browser/Playwright assertion, CLI stdout, DB state diff, parsed config dump.
 10. Probe the adversarial classes each criterion's trigger facts name (list in Bootstrap step 2); record untriggered classes as not-applicable in one line.
 11. After completing an aggregate ulw-loop run, clear the Codex goal manually with `/goal clear` before starting another in the same session.
 12. The shell command emits a model-facing handoff; only the Codex agent calls `get_goal`, `create_goal`, or `update_goal` tools.

package/packages/omo-codex/plugin/components/ulw-loop/src/cli-steering.ts

@@ -5,6 +5,18 @@ import type { SteerUlwLoopResult, UlwLoopSteeringChildGoal, UlwLoopSteeringMutat
 import { ULW_LOOP_STEERING_MUTATION_KINDS, ULW_LOOP_SUCCESS_CRITERION_USER_MODELS, UlwLoopError } from "./types.js";
 
 const SOURCES = ["user_prompt_submit", "finding", "cli"] as const satisfies readonly UlwLoopSteeringSource[];
+const STEERING_KIND_HELP = [
+	`Allowed --kind values: ${ULW_LOOP_STEERING_MUTATION_KINDS.join(", ")}`,
+	"Kind-specific required flags:",
+	"  add_subgoal: --title, --objective, --evidence, --rationale",
+	"  split_subgoal: --goal-id, --children, --evidence, --rationale",
+	"  reorder_pending: --order, --evidence, --rationale",
+	"  revise_pending_wording: --goal-id, --title or --objective, --evidence, --rationale",
+	"  revise_criterion: --goal-id, --criterion-id, one of --scenario/--expected-evidence/--user-model, --evidence, --rationale",
+	"  annotate_ledger: --evidence, --rationale",
+	"  mark_blocked_superseded: --goal-id, optional --replacements, --evidence, --rationale",
+	"Example: omo ulw-loop steer --kind annotate_ledger --evidence \"observed behavior\" --rationale \"why this changes the plan\" --json",
+].join("\n");
 
 export type CliSteeringProposal = UlwLoopSteeringProposal & { readonly goalId?: string; readonly scenario?: string; readonly expectedEvidence?: string; readonly userModel?: UlwLoopSuccessCriterionUserModel };
 
@@ -12,6 +24,7 @@ function isKind(value: string | undefined): value is UlwLoopSteeringMutationKind
 function isSource(value: string | undefined): value is UlwLoopSteeringSource { return value !== undefined && SOURCES.some((source) => source === value); }
 function isModel(value: string): value is UlwLoopSuccessCriterionUserModel { return ULW_LOOP_SUCCESS_CRITERION_USER_MODELS.some((model) => model === value); }
 function fail(message: string, code: string, details: Record<string, unknown>): never { throw new UlwLoopError(message, code, { details }); }
+function kindMessage(prefix: string): string { return `${prefix}\n\n${STEERING_KIND_HELP}`; }
 function text(value: string | undefined, field: string): string | undefined { if (value === undefined) return undefined; const trimmed = value.trim(); if (trimmed.length > 0) return trimmed; return fail(`Empty ${field}.`, "ULW_LOOP_STEERING_FIELD_EMPTY", { field }); }
 function required(argv: readonly string[], flag: string): string { const value = text(readValue(argv, flag), flag); return value ?? fail(`Missing ${flag}.`, "ULW_LOOP_STEERING_FIELD_REQUIRED", { flag }); }
 function requiredGoal(argv: readonly string[]): string { const value = text(parseGoalArg(argv), "--goal-id"); return value ?? fail("Missing --goal-id.", "ULW_LOOP_GOAL_ID_REQUIRED", { flag: "--goal-id" }); }
@@ -22,7 +35,7 @@ function objectText(value: object, key: string): string | undefined { const cand
 export function parseSteeringKind(argv: readonly string[]): UlwLoopSteeringMutationKind {
 	const value = readValue(argv, "--kind");
 	if (isKind(value)) return value;
-	return value === undefined ? fail("Missing --kind.", "ULW_LOOP_STEERING_KIND_REQUIRED", { flag: "--kind" }) : fail(`Invalid --kind: ${value}.`, "ULW_LOOP_STEERING_KIND_INVALID", { value, expected: ULW_LOOP_STEERING_MUTATION_KINDS });
+	return value === undefined ? fail(kindMessage("Missing --kind."), "ULW_LOOP_STEERING_KIND_REQUIRED", { flag: "--kind", expected: ULW_LOOP_STEERING_MUTATION_KINDS, usage: STEERING_KIND_HELP }) : fail(kindMessage(`Invalid --kind: ${value}.`), "ULW_LOOP_STEERING_KIND_INVALID", { value, expected: ULW_LOOP_STEERING_MUTATION_KINDS, usage: STEERING_KIND_HELP });
 }
 
 export function parseSteeringSource(argv: readonly string[]): UlwLoopSteeringSource {

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

@@ -3,7 +3,7 @@ import { isUlwLoopSubcommand, ulwLoopCommand } from "./cli-commands.js";
 import { runPreToolUseGoalBudgetGuardCli, runUlwLoopHookCli } from "./codex-hook.js";
 
 const TOP_LEVEL_HELP =
-	"Usage:\n  omo ulw-loop <subcommand> [args]\n  omo hook user-prompt-submit         (Codex UserPromptSubmit hook)\n  omo help | --help | -h              (this message)\n\nRun `omo ulw-loop help` for ulw-loop subcommands.\n";
+	"Usage:\n  omo ulw-loop <subcommand> [args]\n  omo hook user-prompt-submit [--with-ultrawork]  (Codex UserPromptSubmit hook)\n  omo help | --help | -h                          (this message)\n\nRun `omo ulw-loop help` for ulw-loop subcommands.\n";
 
 async function main(): Promise<number> {
 	const argv = process.argv.slice(2);
@@ -16,7 +16,9 @@ async function main(): Promise<number> {
 	if (command === "hook") {
 		const sub = argv[1];
 		if (sub === "user-prompt-submit") {
-			await runUlwLoopHookCli(process.stdin, process.stdout);
+			await runUlwLoopHookCli(process.stdin, process.stdout, {
+				includeUltraworkDirective: argv.includes("--with-ultrawork"),
+			});
 			return 0;
 		}
 		if (sub === "pre-tool-use") {

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

@@ -1,5 +1,6 @@
 import type { UlwLoopScope } from "./paths.js";
 import { parseUlwLoopSteeringDirective, steerUlwLoop } from "./steering.js";
+import { buildUltraworkDirectiveOutput } from "./ultrawork-directive.js";
 
 export interface UserPromptSubmitPayload {
 	readonly cwd: string;
@@ -8,10 +9,14 @@ export interface UserPromptSubmitPayload {
 	readonly permission_mode?: string;
 	readonly prompt: string;
 	readonly session_id: string;
-	readonly transcript_path?: string;
+	readonly transcript_path?: string | null;
 	readonly turn_id?: string;
 }
 
+export interface UserPromptSubmitHookOptions {
+	readonly includeUltraworkDirective?: boolean;
+}
+
 export interface PreToolUsePayload {
 	readonly cwd: string;
 	readonly hook_event_name: "PreToolUse";
@@ -60,11 +65,17 @@ export function parsePreToolUsePayload(raw: string): PreToolUsePayload | null {
 	}
 }
 
-export async function applyUserPromptUlwLoopSteering(payload: UserPromptSubmitPayload): Promise<string> {
+export async function applyUserPromptUlwLoopSteering(
+	payload: UserPromptSubmitPayload,
+	options: UserPromptSubmitHookOptions = {},
+): Promise<string> {
 	try {
 		if (payload.hook_event_name !== "UserPromptSubmit") return "";
 		const proposal = parseUlwLoopSteeringDirective(payload.prompt);
-		if (proposal === null) return "";
+		if (proposal === null) {
+			if (hasSteeringDirectiveMarker(payload.prompt)) return "";
+			return options.includeUltraworkDirective ? buildUltraworkDirectiveOutput(payload) : "";
+		}
 		const result = await steerUlwLoop(payload.cwd, proposal, payloadScope(payload));
 		if (!result.accepted) return "";
 		return JSON.stringify({
@@ -79,6 +90,10 @@ export async function applyUserPromptUlwLoopSteering(payload: UserPromptSubmitPa
 	}
 }
 
+function hasSteeringDirectiveMarker(prompt: string): boolean {
+	return /(?:^|\s)(?:OMO_ULW_LOOP_STEER|omo\.ulw-loop\.steer|omo ulw-loop steer):/u.test(prompt);
+}
+
 function payloadScope(payload: UserPromptSubmitPayload): UlwLoopScope {
 	return { sessionId: payload.session_id };
 }
@@ -98,11 +113,15 @@ export function applyPreToolUseGoalBudgetGuard(payload: PreToolUsePayload): stri
 	return `${JSON.stringify(output)}\n`;
 }
 
-export async function runUlwLoopHookCli(stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream): Promise<void> {
+export async function runUlwLoopHookCli(
+	stdin: NodeJS.ReadableStream,
+	stdout: NodeJS.WritableStream,
+	options: UserPromptSubmitHookOptions = {},
+): Promise<void> {
 	try {
 		const payload = parseUserPromptSubmitPayload(await readAll(stdin));
 		if (payload === null) return;
-		const output = await applyUserPromptUlwLoopSteering(payload);
+		const output = await applyUserPromptUlwLoopSteering(payload, options);
 		if (output.length > 0) stdout.write(output);
 	} catch (error) {
 		if (error instanceof Error) return;
@@ -132,7 +151,10 @@ function isUserPromptSubmitPayload(value: unknown): value is UserPromptSubmitPay
 		typeof value["cwd"] === "string" &&
 		typeof value["prompt"] === "string" &&
 		typeof value["session_id"] === "string" &&
-		["model", "permission_mode", "transcript_path", "turn_id"].every((key) => optionalString(value[key]))
+		["model", "permission_mode", "turn_id"].every((key) => optionalString(value[key])) &&
+		(value["transcript_path"] === undefined ||
+			value["transcript_path"] === null ||
+			typeof value["transcript_path"] === "string")
 	);
 }
 

package/packages/omo-codex/plugin/components/ulw-loop/src/ultrawork-directive.ts

@@ -0,0 +1,113 @@
+import { readFileSync } from "node:fs";
+
+export interface UltraworkDirectiveInput {
+	readonly prompt: string;
+	readonly transcript_path?: string | null;
+}
+
+interface UserPromptSubmitHookOutput {
+	readonly hookSpecificOutput: {
+		readonly hookEventName: "UserPromptSubmit";
+		readonly additionalContext: string;
+	};
+}
+
+const ULTRAWORK_DIRECTIVE = readFileSync(new URL("../directive.md", import.meta.url), "utf8");
+const ULTRAWORK_CURRENT_PROMPT_PATTERN = /(?:ultrawork|ulw)/i;
+const ULTRAWORK_DIRECTIVE_MARKER = "<ultrawork-mode>";
+const TRANSCRIPT_SEARCH_BYTES = 512_000;
+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",
+] as const;
+
+export function buildUltraworkDirectiveOutput(input: UltraworkDirectiveInput): string {
+	if (isContextPressureRecoveryPrompt(input.prompt)) return "";
+	if (hasUltraworkDirectiveAlreadyInTranscript(input.transcript_path)) return "";
+	if (isContextPressureTranscript(input.transcript_path)) return "";
+	return isUltraworkPrompt(input.prompt) ? formatAdditionalContextOutput(ULTRAWORK_DIRECTIVE) : "";
+}
+
+function hasUltraworkDirectiveAlreadyInTranscript(transcriptPath: string | null | undefined): boolean {
+	if (transcriptPath === undefined || transcriptPath === null) return false;
+	try {
+		const rawTranscript = readTranscriptTail(transcriptPath);
+		for (const line of rawTranscript.split(/\r?\n/)) {
+			const parsed = parseJsonLine(line);
+			if (!isRecord(parsed)) continue;
+			const hookSpecificOutput = parsed["hookSpecificOutput"];
+			if (!isRecord(hookSpecificOutput)) continue;
+			if (hookSpecificOutput["hookEventName"] !== "UserPromptSubmit") continue;
+			if (
+				typeof hookSpecificOutput["additionalContext"] === "string" &&
+				hookSpecificOutput["additionalContext"].includes(ULTRAWORK_DIRECTIVE_MARKER)
+			) {
+				return true;
+			}
+		}
+	} catch (error) {
+		if (error instanceof Error) return false;
+		throw error;
+	}
+	return false;
+}
+
+function readTranscriptTail(transcriptPath: string): string {
+	const rawTranscript = readFileSync(transcriptPath);
+	return rawTranscript.subarray(Math.max(0, rawTranscript.byteLength - TRANSCRIPT_SEARCH_BYTES)).toString("utf8");
+}
+
+function isUltraworkPrompt(prompt: string): boolean {
+	return ULTRAWORK_CURRENT_PROMPT_PATTERN.test(prompt);
+}
+
+function isContextPressureRecoveryPrompt(prompt: string): boolean {
+	const normalizedPrompt = prompt.toLowerCase();
+	return CONTEXT_PRESSURE_MARKERS.some((marker) => normalizedPrompt.includes(marker));
+}
+
+function isContextPressureTranscript(transcriptPath: string | null | undefined): boolean {
+	if (transcriptPath === undefined || transcriptPath === null) return false;
+	try {
+		return isContextPressureRecoveryPrompt(readTranscriptTail(transcriptPath));
+	} catch (error) {
+		if (error instanceof Error) return false;
+		throw error;
+	}
+}
+
+function formatAdditionalContextOutput(additionalContext: string): string {
+	const normalizedContext = normalizeAdditionalContext(additionalContext);
+	if (normalizedContext.length === 0) return "";
+	const output: UserPromptSubmitHookOutput = {
+		hookSpecificOutput: {
+			hookEventName: "UserPromptSubmit",
+			additionalContext: normalizedContext,
+		},
+	};
+	return `${JSON.stringify(output)}\n`;
+}
+
+function normalizeAdditionalContext(additionalContext: string): string {
+	return additionalContext.replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim();
+}
+
+function parseJsonLine(line: string): unknown | null {
+	if (line.trim().length === 0) return null;
+	try {
+		const parsed: unknown = JSON.parse(line);
+		return parsed;
+	} catch (error) {
+		if (error instanceof Error) return null;
+		throw error;
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/packages/omo-codex/plugin/components/ulw-loop/test/cli-entrypoint.test.ts

@@ -23,6 +23,15 @@ function sanitizedEnv(): NodeJS.ProcessEnv {
 }
 
 async function runProcess(command: string, args: readonly string[], cwd: string): Promise<CliResult> {
+	return runProcessWithInput(command, args, cwd, "");
+}
+
+async function runProcessWithInput(
+	command: string,
+	args: readonly string[],
+	cwd: string,
+	input: string,
+): Promise<CliResult> {
 	return new Promise((resolvePromise, reject) => {
 		const child = spawn(command, [...args], { cwd, env: sanitizedEnv() });
 		const stdout: Buffer[] = [];
@@ -37,13 +46,14 @@ async function runProcess(command: string, args: readonly string[], cwd: string)
 				stderr: Buffer.concat(stderr).toString("utf8"),
 			});
 		});
+		child.stdin.end(input);
 	});
 }
 
 let workspace: string;
 
-async function runCli(args: readonly string[]): Promise<CliResult> {
-	return runProcess(process.execPath, [builtCli, ...args], workspace);
+async function runCli(args: readonly string[], input = ""): Promise<CliResult> {
+	return runProcessWithInput(process.execPath, [builtCli, ...args], workspace, input);
 }
 
 beforeAll(async () => {
@@ -92,4 +102,25 @@ describe("dist/cli.js entrypoint dispatch", () => {
 		expect(result.code).toBe(1);
 		expect(result.stderr).toContain("[omo] unknown command: frobnicate");
 	});
+
+	it("#given standalone ulw-loop hook asks for ultrawork context #when user prompt is ulw #then emits the ultrawork directive", async () => {
+		const payload = {
+			cwd: workspace,
+			hook_event_name: "UserPromptSubmit",
+			model: "gpt-5.5",
+			permission_mode: "default",
+			prompt: "ulw this change",
+			session_id: "s1",
+			transcript_path: null,
+			turn_id: "t1",
+		};
+
+		const result = await runCli(["hook", "user-prompt-submit", "--with-ultrawork"], `${JSON.stringify(payload)}\n`);
+		const parsed = JSON.parse(result.stdout);
+
+		expect(result.code).toBe(0);
+		expect(result.stderr).toBe("");
+		expect(parsed.hookSpecificOutput.hookEventName).toBe("UserPromptSubmit");
+		expect(parsed.hookSpecificOutput.additionalContext).toMatch(/^<ultrawork-mode>/);
+	});
 });