oh-my-customcodex 0.4.13 → 0.4.17

package/README.md

@@ -13,7 +13,7 @@
 
 **[한국어 문서 (Korean)](./README_ko.md)**
 
-49 agents. 117 skills. 22 rules. One command.
+49 agents. 118 skills. 22 rules. One command.
 
 ```bash
 npm install -g oh-my-customcodex && cd your-project && omcustomcodex init
@@ -134,7 +134,7 @@ Each agent declares its tools, model, memory scope, and limitations in YAML fron
 
 ---
 
-### Skills (117)
+### Skills (118)
 
 | Category | Count | Includes |
 |----------|-------|----------|
@@ -170,6 +170,7 @@ All commands are invoked inside the oh-my-customcodex GPT Codex + OMX session.
 | `/ambiguity-gate` | Pre-routing ambiguity analysis |
 | `/pre-generation-arch-check` | Check architecture risks before implementation |
 | `/adversarial-review` | Attacker-mindset security code review |
+| `/omcustomcodex:goal` | Keep a concrete objective in view through planning, execution, and verification |
 | `/pipeline` | Execute YAML-defined pipelines |
 | `/pipeline resume` | Resume a halted pipeline from last failure point |
 
@@ -286,7 +287,7 @@ your-project/
 │   ├── contexts/               # 4 shared context files
 │   └── ontology/               # Knowledge graph for RAG
 ├── .agents/
-│   └── skills/                 # 117 installed skill modules
+│   └── skills/                 # 118 installed skill modules
 └── guides/                     # 47 reference documents
 ```
 

package/dist/cli/index.js

@@ -1019,7 +1019,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         this._exitCallback = (err) => {
           if (err.code !== "commander.executeSubCommandAsync") {
             throw err;
-          } else {}
+          }
         };
       }
       return this;
@@ -3091,7 +3091,7 @@ var init_package = __esm(() => {
     workspaces: [
       "packages/*"
     ],
-    version: "0.4.13",
+    version: "0.4.17",
     requiresCC: ">=2.1.121",
     claudeCode: {
       minimumVersion: "2.1.121",
@@ -10179,6 +10179,23 @@ function sortProjects(projects) {
     return a.name.localeCompare(b.name);
   });
 }
+async function buildRegistryProjectInfo(projectPath, entry, options, home, currentVersion) {
+  if (!matchesSearchPaths(projectPath, options.paths))
+    return null;
+  if (!isUnderHome(projectPath, home))
+    return null;
+  if (!await fileExists(projectPath))
+    return null;
+  return {
+    name: basename5(projectPath),
+    path: projectPath,
+    version: entry.version || null,
+    installedAt: entry.installedAt || null,
+    updatedAt: entry.updatedAt || null,
+    status: computeStatus(entry.version || null, currentVersion),
+    detectionMethod: "registry"
+  };
+}
 async function findProjects(options = {}) {
   const currentVersion = await getTemplateVersion();
   const registry = await readRegistry();
@@ -10192,19 +10209,9 @@ async function findProjects(options = {}) {
   const results = [];
   const home = process.env.HOME ?? homedir3();
   for (const [projectPath, entry] of Object.entries(registry.projects)) {
-    if (!matchesSearchPaths(projectPath, options.paths))
-      continue;
-    if (!isUnderHome(projectPath, home))
-      continue;
-    results.push({
-      name: basename5(projectPath),
-      path: projectPath,
-      version: entry.version || null,
-      installedAt: entry.installedAt || null,
-      updatedAt: entry.updatedAt || null,
-      status: computeStatus(entry.version || null, currentVersion),
-      detectionMethod: "registry"
-    });
+    const project = await buildRegistryProjectInfo(projectPath, entry, options, home, currentVersion);
+    if (project)
+      results.push(project);
   }
   return sortProjects(results);
 }
@@ -19772,7 +19779,7 @@ var require_dbcs_codec = __commonJS((exports) => {
           if (resCode !== undefined) {
             dbcsCode = resCode;
             nextChar = uCode;
-          } else {}
+          }
         }
         seqObj = undefined;
       } else if (uCode >= 0) {
@@ -19837,7 +19844,7 @@ var require_dbcs_codec = __commonJS((exports) => {
           newBuf[j2++] = dbcsCode >> 8;
           newBuf[j2++] = dbcsCode & 255;
         }
-      } else {}
+      }
       this.seqObj = undefined;
     }
     if (this.leadSurrogate !== -1) {
@@ -31413,6 +31420,7 @@ async function runFullUpdatePostProcessing(options, result, config) {
     const removed = await removeDeprecatedFiles(options.targetDir, options);
     result.removedDeprecatedFiles = removed;
     if (!options.dryRun) {
+      await ensureStatusLineConfig(options.targetDir);
       await updateEntryDoc(options.targetDir, config, options);
     }
   }
@@ -31431,6 +31439,34 @@ async function runFullUpdatePostProcessing(options, result, config) {
     });
   }
 }
+async function ensureStatusLineConfig(targetDir) {
+  const layout = getProviderLayout();
+  const settingsPath = join17(targetDir, layout.rootDir, "settings.local.json");
+  const statusLineConfig = {
+    type: "command",
+    command: `${layout.rootDir}/statusline.sh`,
+    padding: 0,
+    refreshInterval: 10
+  };
+  if (!await fileExists(settingsPath)) {
+    await ensureDirectory(join17(settingsPath, ".."));
+    await writeJsonFile(settingsPath, { statusLine: statusLineConfig });
+    return;
+  }
+  const settings = await readJsonFile(settingsPath);
+  const statusLine = settings.statusLine;
+  if (!statusLine || typeof statusLine !== "object" || Array.isArray(statusLine)) {
+    settings.statusLine = statusLineConfig;
+    await writeJsonFile(settingsPath, settings);
+    return;
+  }
+  const mergedStatusLine = statusLine;
+  if (mergedStatusLine.refreshInterval === undefined) {
+    mergedStatusLine.refreshInterval = statusLineConfig.refreshInterval;
+    settings.statusLine = mergedStatusLine;
+    await writeJsonFile(settingsPath, settings);
+  }
+}
 function compareSemver2(a, b) {
   const pa = a.split(".").map(Number);
   const pb = b.split(".").map(Number);
@@ -31502,6 +31538,15 @@ function checkAndInstallOmxAfterUpdate() {
     }
   }
 }
+async function handleNoUpdateResult(options, result) {
+  const isFullUpdate = !options.components || options.components.length === 0;
+  if (isFullUpdate && !options.dryRun) {
+    await ensureStatusLineConfig(options.targetDir);
+  }
+  info("update.no_updates");
+  result.success = true;
+  result.skippedComponents = options.components || getAllUpdateComponents();
+}
 async function update(options) {
   const result = createUpdateResult();
   try {
@@ -31520,9 +31565,7 @@ async function update(options) {
     const updateCheck = await checkForUpdates(options.targetDir);
     result.newVersion = updateCheck.latestVersion;
     if (!updateCheck.hasUpdates && !options.force) {
-      info("update.no_updates");
-      result.success = true;
-      result.skippedComponents = options.components || getAllUpdateComponents();
+      await handleNoUpdateResult(options, result);
       return result;
     }
     await handleBackupIfRequested(options.targetDir, !!options.backup, result);
@@ -32022,8 +32065,10 @@ function reportProjectUpdateResult(project, result, currentVersion) {
 }
 async function updateAllProjects(options) {
   const { findProjects: findProjects2 } = await Promise.resolve().then(() => (init_projects(), exports_projects));
+  const { cleanRegistry: cleanRegistry2 } = await Promise.resolve().then(() => (init_registry(), exports_registry));
   const currentVersion = package_default.version;
   console.log(i18n.t("cli.update.allScanning"));
+  await cleanRegistry2();
   const projects = await findProjects2();
   if (projects.length === 0) {
     console.log(i18n.t("cli.update.allNoneFound"));

package/dist/index.js

@@ -2180,7 +2180,7 @@ var package_default = {
   workspaces: [
     "packages/*"
   ],
-  version: "0.4.13",
+  version: "0.4.17",
   requiresCC: ">=2.1.121",
   claudeCode: {
     minimumVersion: "2.1.121",
@@ -5015,6 +5015,7 @@ async function runFullUpdatePostProcessing(options, result, config) {
     const removed = await removeDeprecatedFiles(options.targetDir, options);
     result.removedDeprecatedFiles = removed;
     if (!options.dryRun) {
+      await ensureStatusLineConfig(options.targetDir);
       await updateEntryDoc(options.targetDir, config, options);
     }
   }
@@ -5033,6 +5034,34 @@ async function runFullUpdatePostProcessing(options, result, config) {
     });
   }
 }
+async function ensureStatusLineConfig(targetDir) {
+  const layout = getProviderLayout();
+  const settingsPath = join8(targetDir, layout.rootDir, "settings.local.json");
+  const statusLineConfig = {
+    type: "command",
+    command: `${layout.rootDir}/statusline.sh`,
+    padding: 0,
+    refreshInterval: 10
+  };
+  if (!await fileExists(settingsPath)) {
+    await ensureDirectory(join8(settingsPath, ".."));
+    await writeJsonFile(settingsPath, { statusLine: statusLineConfig });
+    return;
+  }
+  const settings = await readJsonFile(settingsPath);
+  const statusLine = settings.statusLine;
+  if (!statusLine || typeof statusLine !== "object" || Array.isArray(statusLine)) {
+    settings.statusLine = statusLineConfig;
+    await writeJsonFile(settingsPath, settings);
+    return;
+  }
+  const mergedStatusLine = statusLine;
+  if (mergedStatusLine.refreshInterval === undefined) {
+    mergedStatusLine.refreshInterval = statusLineConfig.refreshInterval;
+    settings.statusLine = mergedStatusLine;
+    await writeJsonFile(settingsPath, settings);
+  }
+}
 function compareSemver(a, b) {
   const pa = a.split(".").map(Number);
   const pb = b.split(".").map(Number);
@@ -5104,6 +5133,15 @@ function checkAndInstallOmxAfterUpdate() {
     }
   }
 }
+async function handleNoUpdateResult(options, result) {
+  const isFullUpdate = !options.components || options.components.length === 0;
+  if (isFullUpdate && !options.dryRun) {
+    await ensureStatusLineConfig(options.targetDir);
+  }
+  info("update.no_updates");
+  result.success = true;
+  result.skippedComponents = options.components || getAllUpdateComponents();
+}
 async function update(options) {
   const result = createUpdateResult();
   try {
@@ -5122,9 +5160,7 @@ async function update(options) {
     const updateCheck = await checkForUpdates(options.targetDir);
     result.newVersion = updateCheck.latestVersion;
     if (!updateCheck.hasUpdates && !options.force) {
-      info("update.no_updates");
-      result.success = true;
-      result.skippedComponents = options.components || getAllUpdateComponents();
+      await handleNoUpdateResult(options, result);
       return result;
     }
     await handleBackupIfRequested(options.targetDir, !!options.backup, result);

package/package.json

@@ -3,7 +3,7 @@
   "workspaces": [
     "packages/*"
   ],
-  "version": "0.4.13",
+  "version": "0.4.17",
   "requiresCC": ">=2.1.121",
   "claudeCode": {
     "minimumVersion": "2.1.121",

package/templates/.claude/hooks/hooks.json

@@ -438,6 +438,7 @@
             "command": "bash .codex/hooks/scripts/context-budget-advisor.sh"
           }
         ],
+        "continueOnBlock": true,
         "description": "Context budget advisor — track tool usage patterns and advise ecomode activation"
       },
       {
@@ -448,6 +449,7 @@
             "command": "bash .codex/hooks/scripts/stuck-detector.sh"
           }
         ],
+        "continueOnBlock": true,
         "description": "Detect repetitive failure loops and advise recovery strategies"
       },
       {
@@ -458,6 +460,7 @@
             "command": "bash .codex/hooks/scripts/cost-cap-advisor.sh"
           }
         ],
+        "continueOnBlock": true,
         "description": "Advisory cost cap monitoring — warn when session cost approaches configurable limit"
       },
       {

package/templates/.claude/hooks/scripts/context-budget-advisor.sh

@@ -8,13 +8,14 @@ command -v jq >/dev/null 2>&1 || exit 0
 # Context Budget Advisor Hook
 # Trigger: PostToolUse (Edit/Write/Agent/Task/Read/Glob/Grep/Bash)
 # Purpose: Monitor context usage and advise ecomode activation based on task type
-# Protocol: stdin JSON -> stdout pass-through, exit 0 always
+# Protocol: stdin JSON -> stdout pass-through; exit 2 only for continueOnBlock signals
 
 input=$(cat)
 
 # Read context info from status file if available
-STATUS_FILE="/tmp/.codex-env-status-${PPID}"
+COST_FILE="/tmp/.codex-cost-${PPID}"
 BUDGET_FILE="/tmp/.codex-context-budget-${PPID}"
+SIGNAL_FILE="/tmp/.codex-context-budget-signal-${PPID}"
 
 # Initialize budget tracking file
 if [ ! -f "$BUDGET_FILE" ]; then
@@ -77,6 +78,43 @@ case "$task_type" in
   *)             THRESHOLD=80 ;;
 esac
 
+# Use statusline bridge data when available. Exiting 2 with continueOnBlock=true
+# turns a high-context advisory into model-visible feedback without halting.
+ctx_pct="0"
+ctx_timestamp="0"
+if [ -f "$COST_FILE" ]; then
+  IFS=$'\t' read -r _cost_usd ctx_pct ctx_timestamp _rl_5h _rl_7d _rl_5h_resets _rl_7d_resets < "$COST_FILE" 2>/dev/null || true
+fi
+
+ctx_int="${ctx_pct%%.*}"
+case "$ctx_int" in
+  ''|*[!0-9]*) ctx_int=0 ;;
+esac
+case "$ctx_timestamp" in
+  ''|*[!0-9]*) ctx_timestamp=0 ;;
+esac
+
+now=$(date +%s)
+age=$((now - ${ctx_timestamp:-0}))
+signal_key="${task_type}:${THRESHOLD}"
+last_signal=""
+if [ -f "$SIGNAL_FILE" ]; then
+  last_signal=$(cat "$SIGNAL_FILE" 2>/dev/null || echo "")
+fi
+
+if [ "$age" -le 60 ] && [ "$ctx_int" -ge "$THRESHOLD" ] && [ "$last_signal" != "$signal_key" ]; then
+  echo "[Context Budget] ${ctx_int}% context used meets ${task_type} threshold ${THRESHOLD}%" >&2
+  echo "[Context Budget] Switch to ecomode, compact, or narrow the remaining task before continuing." >&2
+  echo "$signal_key" > "$SIGNAL_FILE"
+  echo "$input"
+  HOOK_END=$(date +%s%N 2>/dev/null || echo 0)
+  if [ "$HOOK_START" != "0" ] && [ "$HOOK_END" != "0" ]; then
+    HOOK_MS=$(( (HOOK_END - HOOK_START) / 1000000 ))
+    echo "[Hook Perf] $(basename "$0"): ${HOOK_MS}ms" >> "/tmp/.codex-hook-perf-${PPID}.log"
+  fi
+  exit 2
+fi
+
 # Emit advisory at milestones (every 25 tool calls)
 if [ "$tool_count" -gt 0 ] && [ $((tool_count % 25)) -eq 0 ]; then
   echo "[Context Budget] Task: ${task_type} | Threshold: ${THRESHOLD}% | Tools used: ${tool_count}" >&2

package/templates/.claude/hooks/scripts/cost-cap-advisor.sh

@@ -2,7 +2,7 @@
 # cost-cap-advisor.sh — Advisory hook for session cost monitoring
 # Trigger: PostToolUse (Agent/Task)
 # Purpose: Warn when session cost approaches configurable cap
-# Protocol: stdin JSON -> stdout pass-through, exit 0 always (advisory only, R010)
+# Protocol: stdin JSON -> stdout pass-through; exit 2 only for continueOnBlock wrap-up signals
 
 input=$(cat)
 
@@ -30,10 +30,13 @@ if ! printf '%f' "$cost_usd" >/dev/null 2>&1; then
   echo "$input"
   exit 0
 fi
+if ! printf '%f' "$COST_CAP" >/dev/null 2>&1; then
+  echo "$input"
+  exit 0
+fi
 
 # Calculate percentage of cap used
-# Use bc for float arithmetic
-cost_pct=$(echo "scale=0; $cost_usd * 100 / $COST_CAP" | bc 2>/dev/null || echo "0")
+cost_pct=$(awk -v cost="$cost_usd" -v cap="$COST_CAP" 'BEGIN { if (cap <= 0) print 0; else printf "%d", (cost * 100 / cap) }' 2>/dev/null || echo "0")
 
 # Staleness check — skip if data is older than 60 seconds
 now=$(date +%s)
@@ -54,6 +57,8 @@ if [ "$cost_pct" -ge 100 ] && [ "$last_level" != "100" ]; then
   echo "[Cost Cap] Session cost \$${cost_usd} has reached cap \$${COST_CAP} (${cost_pct}%)" >&2
   echo "[Cost Cap] Consider wrapping up or increasing CLAUDE_COST_CAP" >&2
   echo "100" > "$ADVISORY_FILE"
+  echo "$input"
+  exit 2
 elif [ "$cost_pct" -ge 90 ] && [ "$last_level" != "90" ] && [ "$last_level" != "100" ]; then
   echo "[Cost Cap] Session cost \$${cost_usd} at 90% of cap \$${COST_CAP}" >&2
   echo "[Cost Cap] Ecomode recommended — consider /compact" >&2

package/templates/.claude/hooks/scripts/omcustom-auto-update.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SessionStart auto-update hook — interactive omcodex update check
+# SessionStart auto-update hook — interactive omcustomcodex update check
 # Trigger: SessionStart (runs BEFORE session-env-check.sh)
 # Purpose: Check for oh-my-customcodex updates, prompt user, optionally update
 # Protocol: stdin JSON -> stdout pass-through, exit 0 ALWAYS
@@ -135,17 +135,17 @@ if read -r -t "$INPUT_TIMEOUT" answer </dev/tty 2>/dev/null; then
         echo "  ✓ Updated to v${LATEST_VERSION}" >&2
 
         # Check if project harness should be updated too
-        if [ -f ".omcustomrc.json" ]; then
+        if [ -f ".omcodexrc.json" ] || [ -f ".omcustomrc.json" ]; then
           printf "  Update project harness too? [y/N] " >/dev/tty 2>/dev/null
           if read -r -t "$INPUT_TIMEOUT" harness_answer </dev/tty 2>/dev/null; then
             case "$harness_answer" in
               [yY]|[yY][eE][sS])
                 echo "  Updating project harness..." >&2
-                if command -v omcustom >/dev/null 2>&1; then
-                  omcustom update --force >&2 2>&1 || echo "  ⚠ Harness update failed (non-blocking)" >&2
+                if command -v omcustomcodex >/dev/null 2>&1; then
+                  omcustomcodex update --force >&2 2>&1 || echo "  ⚠ Harness update failed (non-blocking)" >&2
                   echo "  ✓ Project harness updated" >&2
                 else
-                  echo "  ⚠ omcustom command not found after install" >&2
+                  echo "  ⚠ omcustomcodex command not found after install" >&2
                 fi
                 ;;
               *)

package/templates/.claude/hooks/scripts/session-env-check.sh

@@ -126,8 +126,10 @@ OMCUSTOM_UPDATE_STATUS="unknown"
 INSTALLED_VERSION=""
 CACHED_LATEST=""
 
-# Read installed version from .omcustomrc.json
-if [ -f ".omcustomrc.json" ]; then
+# Read installed version from the Codex config, falling back to the legacy parent config.
+if [ -f ".omcodexrc.json" ]; then
+  INSTALLED_VERSION=$(grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' .omcodexrc.json 2>/dev/null | head -1 | grep -o '"[^"]*"$' | tr -d '"')
+elif [ -f ".omcustomrc.json" ]; then
   INSTALLED_VERSION=$(grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' .omcustomrc.json 2>/dev/null | head -1 | grep -o '"[^"]*"$' | tr -d '"')
 fi
 
@@ -222,8 +224,8 @@ case "$DRIFT_STATUS" in
 esac
 echo "" >&2
 echo "  [Lockfile Drift]" >&2
-echo "  Note: file-level lockfile drift (template hash changes) is checked via 'omcodex doctor'" >&2
-echo "  Run 'omcodex doctor' to detect modified/removed template files since install." >&2
+echo "  Note: file-level lockfile drift (template hash changes) is checked via 'omcustomcodex doctor'" >&2
+echo "  Run 'omcustomcodex doctor' to detect modified/removed template files since install." >&2
 echo "------------------------------------" >&2
 
 # SessionEnd hooks timeout (v2.1.74+)
@@ -238,12 +240,12 @@ echo "  [Update Check]" >&2
 if [ -n "$INSTALLED_VERSION" ] && [ -n "$CACHED_LATEST" ]; then
   if [ "$OMCUSTOM_UPDATE_STATUS" = "available" ]; then
     echo "  ⚡ oh-my-customcodex v${CACHED_LATEST} available (current: v${INSTALLED_VERSION})" >&2
-    echo "     Run 'omcodex update' to apply" >&2
+    echo "     Run 'omcustomcodex update' to apply" >&2
   else
     echo "  ✓ oh-my-customcodex is up to date (v${INSTALLED_VERSION})" >&2
   fi
 elif [ -n "$INSTALLED_VERSION" ]; then
-  echo "  ℹ oh-my-customcodex v${INSTALLED_VERSION} (run 'omcodex doctor --updates' to check for updates)" >&2
+  echo "  ℹ oh-my-customcodex v${INSTALLED_VERSION} (run 'omcustomcodex doctor --updates' to check for updates)" >&2
 else
   echo "  ℹ oh-my-customcodex not detected in this project" >&2
 fi

package/templates/.claude/hooks/scripts/stuck-detector.sh

@@ -10,7 +10,7 @@ command -v jq >/dev/null 2>&1 || exit 0
 # Purpose: Detect repetitive failure loops and advise recovery
 # Protocol: stdin JSON -> process -> stdout pass-through
 #   - exit 0: advisory (normal cases, < HARD_BLOCK_THRESHOLD repetitions)
-#   - exit 1: hard block (extreme stuck loops, >= HARD_BLOCK_THRESHOLD repetitions)
+#   - exit 2: conversation block (extreme stuck loops, >= HARD_BLOCK_THRESHOLD repetitions)
 
 # Hard block threshold: consecutive identical operations before blocking
 HARD_BLOCK_THRESHOLD=${CLAUDE_STUCK_THRESHOLD:-3}
@@ -186,7 +186,7 @@ if [ "$hard_block" = true ]; then
     HOOK_MS=$(( (HOOK_END - HOOK_START) / 1000000 ))
     echo "[Hook Perf] $(basename "$0"): ${HOOK_MS}ms" >> "/tmp/.codex-hook-perf-${PPID}.log"
   fi
-  exit 1
+  exit 2
 fi
 
 # Pass through

package/templates/.claude/ontology/skills.yaml

@@ -45,6 +45,10 @@ classes:
     skills: [status, help, lists]
     description: "System information and utilities"
 
+  GoalWorkflowSkill:
+    skills: ["omcustomcodex:goal"]
+    description: "Goal-to-execution workflow coordination"
+
   VerificationSkill:
     skills: [sauron-watch]
     description: "Verification and compliance"
@@ -174,6 +178,16 @@ skills:
     keywords: [review, code-review, best-practices, quality]
     rule_references: []
 
+  "omcustomcodex:goal":
+    class: GoalWorkflowSkill
+    description: "Goal-to-execution workflow for disciplined Codex + OMX task completion"
+    user_invocable: true
+    model_invocable: true
+    scope: core
+    summary: "Keep a concrete objective visible through clarification, planning, execution, verification, and completion reporting"
+    keywords: [goal, omcustomcodex-goal, objective, planning, execution, verification, completion]
+    rule_references: [R020]
+
   docker-best-practices:
     class: BestPracticeSkill
     description: "Docker patterns for optimized containerization"

package/templates/.claude/rules/MUST-agent-design.md

@@ -72,6 +72,7 @@ disableSkillShellExecution: true  # Disable inline shell execution in skills (v2
 <!-- DETAIL: CC Version Compatibility History
 `isolation`, `background`, `maxTurns`, `maxTokens`, `mcpServers`, `hooks`, `permissionMode`, `disallowedTools`, `limitations` are supported in Claude Code v2.1.63+. Hook types `PostCompact`, `Elicitation`, `ElicitationResult` require v2.1.76+. `CwdChanged`, `FileChanged` hook events and `managed-settings.d/` drop-in directory require v2.1.83+. Conditional `if` field for hooks requires v2.1.85+. `PermissionDenied` hook event requires v2.1.88+. `refreshInterval` setting for status line auto-refresh interval added in v2.1.97+. Monitor tool and subprocess sandboxing (`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`, `CLAUDE_CODE_SCRIPT_CAPS`) added in v2.1.98+. Settings resilience (unrecognized hook event names no longer cause settings.json to be ignored) improved in v2.1.101+. PreCompact hook block support (exit 2 / `{"decision":"block"}`) added in v2.1.105+. Skill description listing cap raised from 250 to 1,536 characters in v2.1.105+. Plugin `monitors` manifest key for background monitors added in v2.1.105+. `ENABLE_PROMPT_CACHING_1H` and `FORCE_PROMPT_CACHING_5M` env vars for prompt cache TTL control added in v2.1.108+. Skill tool can now discover and invoke built-in slash commands (`/init`, `/review`, `/security-review`) in v2.1.108+. `/recap` session context feature and `/undo` alias for `/rewind` added in v2.1.108+. `/tui` command and `tui` setting for fullscreen rendering added in v2.1.110+. PushNotification tool for mobile push notifications (Remote Control + config required) added in v2.1.110+. `autoScrollEnabled` config for fullscreen mode added in v2.1.110+. SDK/headless `TRACEPARENT`/`TRACESTATE` distributed trace linking added in v2.1.110+. Bash tool maximum timeout enforcement added in v2.1.110+. Write tool IDE diff feedback (informs model when user edits proposed content) added in v2.1.110+. `--resume`/`--continue` now resurrects unexpired scheduled tasks in v2.1.110+. `/focus` command (separated from Ctrl+O) added in v2.1.110+. `xhigh` effort level for Opus 4.7 (between `high` and `max`; other models fall back to `high`) added in v2.1.111+. `/effort` interactive slider with arrow-key navigation (when called without arguments) added in v2.1.111+. Auto mode no longer requires `--enable-auto-mode` in v2.1.111+. PowerShell tool progressive rollout (`CLAUDE_CODE_USE_POWERSHELL_TOOL` env var) added in v2.1.111+. Read-only bash commands with glob patterns (`ls *.ts`) and `cd <project-dir> &&` prefix no longer trigger permission prompt in v2.1.111+. `/less-permission-prompts` built-in skill for permission allowlist scanning added in v2.1.111+. `/ultrareview` parallel multi-agent cloud code review added in v2.1.111+. `/skills` menu sorting by estimated token count (press `t`) added in v2.1.111+. `OTEL_LOG_RAW_API_BODIES` env var for full API request/response body logging added in v2.1.111+. Plan files named after prompt content (not random words) in v2.1.111+. Plugin error handling improvements (dependency conflict errors, stale version recovery, install recovery) in v2.1.111+.
 `sandbox.network.deniedDomains` setting for domain blocking within `allowedDomains` wildcards added in v2.1.113+. Subagent mid-stream stall detection with auto-fail after 10 minutes added in v2.1.113+. Bash `find -exec`/`-delete` no longer auto-approved under `Bash(find:*)` allow rules in v2.1.113+. Bash deny rules now match exec wrappers (`env`/`sudo`/`watch`/`ionice`/`setsid`) in v2.1.113+. Native binary spawning (per-platform optional dependency) replaces bundled JavaScript in v2.1.113+. `/loop` Esc now cancels pending wakeups in v2.1.113+.
+Agent frontmatter `hooks:` fire when the agent runs as a main-thread agent via `--agent` flag in v2.1.116+. Hook JSON output `terminalSequence` field for desktop notifications, window title changes, and terminal bells without controlling terminal added in v2.1.141+. `claude agents --cwd <path>` for directory-scoped session lists added in v2.1.141+. Background agents launched via `/bg` preserve current permission mode in v2.1.141+. `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` and `ANTHROPIC_WORKSPACE_ID` environment variables added in v2.1.141+ for HTTPS plugin clones and workspace-scoped federation.
 -->
 
 ## Hook Event Types

package/templates/.claude/rules/MUST-orchestrator-coordination.md

@@ -160,6 +160,12 @@ Current guidance:
 - In Claude Code `bypassPermissions`, broader protected-path writes such as `.claude/**`, `.git/**`, and `.vscode/**` are acceptable on v2.1.126+.
 - Keep the `/tmp/{skill}-{timestamp}.md` pattern only as a legacy fallback for older Claude Code versions or sessions that still surface a protected-path prompt.
 
+## Claude Compatibility Background Mode
+
+Claude Code v2.1.141+ preserves the current permission mode when a session is detached with `/bg` or `←←` backgrounding. Earlier versions could revert to the default mode and surprise unattended release flows with permission prompts.
+
+For this Codex port, native Codex/OMX subagents still follow the active Codex runtime tool policy. Claude compatibility prompts should keep delegated write authority explicit when a workflow relies on unattended edits, but v2.1.141+ no longer needs an extra `/bg` permission-mode workaround.
+
 <!-- DETAIL: Autonomous Execution Mode
 
 ## Autonomous Execution Mode

package/templates/.claude/rules/SHOULD-hud-statusline.md

@@ -15,6 +15,8 @@
 
 Format: `─── [Spawn] {subagent_type}:{model} | {description} ───` — implemented in `.codex/hooks/hooks.json` (PreToolUse → Agent/Task matcher). Display for multi-step/parallel/long-running ops only.
 
+> **Claude Code v2.1.141+ compatibility**: Hook JSON output can include `terminalSequence` to emit desktop notifications, window title changes, or terminal bells without a controlling terminal. Treat this as an optional companion to stderr HUD events and the command statusline; do not add terminal-control hook behavior until there is a concrete Codex-compatible UX need.
+
 <!-- DETAIL: HUD Events full spec
 ### When to Display: Multi-step tasks, parallel execution, long-running operations. Skip for single brief operations.
 ### Parallel Display:

package/templates/.claude/skills/goal/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: omcustomcodex:goal
+description: Goal-to-execution workflow for disciplined Codex + OMX task completion
+scope: core
+version: 1.0.0
+user-invocable: true
+argument-hint: "<objective>"
+---
+
+# /omcustomcodex:goal - Goal-To-Execution Workflow
+
+Use `/omcustomcodex:goal <objective>` when the user wants Codex to keep a concrete objective in view until it is genuinely complete.
+
+This is the Codex + OMX port of the upstream goal workflow. It is implemented as a normal skill surface and does not depend on native Codex feature flags such as `features.goals`.
+
+Native runtimes may reserve `/goal` for their own session-level completion tracker. Keep this workflow on the `omcustomcodex:` namespace so the workflow remains callable without shadowing the native command.
+
+## Contract
+
+When invoked with an objective:
+
+1. Treat the supplied text as the concrete goal.
+2. Ask only for requirements that are materially missing, risky, or blocking.
+3. Inspect the relevant repository context before planning implementation.
+4. Produce a short execution plan for non-trivial work.
+5. Execute using existing project conventions, routing skills, and specialist agents when useful.
+6. Verify completion before claiming the goal is done.
+7. Report changed files, verification evidence, and remaining risks.
+
+## Workflow
+
+### 1. Capture Goal
+
+Restate the objective in one sentence. If the runtime exposes goal tracking, register the objective there. Otherwise keep the objective visible in the active task state.
+
+Do not broaden the goal beyond the user's words without confirming the added scope.
+
+### 2. Clarify Only Blockers
+
+Ask at most three short questions, and only when the answer changes the implementation path or risk profile. If reasonable defaults exist, state the assumption and continue.
+
+### 3. Inspect Context
+
+Search and read the smallest useful set of files before editing. Prefer `rg`/`rg --files` for repository discovery. Identify:
+
+- Existing implementation patterns.
+- Tests or validators that cover the affected surface.
+- Provider-boundary constraints for this repository.
+- User or worktree changes that must be preserved.
+
+### 4. Plan
+
+For non-trivial work, produce a concise plan with:
+
+- Files or modules likely to change.
+- Verification commands.
+- Risks or assumptions.
+
+Skip the visible plan for tiny, obvious changes, but still do the context check.
+
+### 5. Execute
+
+Use the repository's established tools and style. Keep edits scoped to the goal. Delegate through routing skills or agents when the task crosses ownership boundaries, needs specialized review, or benefits from parallel independent work.
+
+In oh-my-customcodex, use `omcustomcodex` in command examples and operator guidance. Do not introduce `omcustom` instructions.
+
+### 6. Verify
+
+Run the narrowest meaningful verification first, then broaden when the change touches shared behavior, generated catalogs, release flow, or user-facing docs. If verification cannot run, report why.
+
+### 7. Complete
+
+Finish with:
+
+- What changed.
+- Verification evidence.
+- Remaining risks or follow-up work.
+
+Do not mark the goal complete until the acceptance criteria are satisfied or the user explicitly accepts a partial result.
+
+## Acceptance Checklist
+
+- Objective stayed fixed unless the user changed it.
+- Blocking ambiguity was resolved or called out.
+- Relevant context was inspected before edits.
+- Implementation followed local patterns.
+- Verification evidence is current.
+- Final response includes changed files and residual risk.