@nodii/dev 0.6.25 → 0.6.27

package/README.md

@@ -351,19 +351,40 @@ nodii-dev docs upload PATH... --class ruling|conformance|editorial
 nodii-dev docs ratify --domain KEY [--domain KEY ...] --decision DECISION.json [--wait]
 nodii-dev docs parked [CODE] [--status pending|acknowledged]
 
-nodii-dev harness install [--include-drafts] [--adopt PATH,...] [--dry-run]
-nodii-dev harness update [--include-drafts] [--adopt PATH,...] [--dry-run]
+nodii-dev harness install [--include-drafts] [--adopt PATH,...] [--dry-run] [--system]
+nodii-dev harness update [--include-drafts] [--adopt PATH,...] [--dry-run] [--system]
 nodii-dev harness check [--json]               # 0 current, 1 differs from Dev, 2 no harness
 nodii-dev harness update --check               # the same check
 ```
 
-`harness install` and `harness update` merge the two safety hooks into
-`.claude/settings.json`; every installed hook invokes only `nodii-dev`. The
+`harness install` and `harness update` merge the safety hooks into both
+`.claude/settings.json` and `.codex/hooks.json`; every installed hook invokes
+only `nodii-dev`. The
 pre-hook blocks edits outside a lane's optional `ownedPaths`, generated UI/API
 files, unsafe Git operations, stale or missing review receipts, lane identity
 changes, production-secret/test-auth bypasses, cleanup of Docker resources the
 run did not create, and deploy/apply commands without an exact grant. Allowed
-calls produce no output.
+calls produce no output. Codex receives runtime-native `Bash` and `apply_patch`
+matchers, JSON denials, and `additionalContext` nudges. A compact session start
+prints the current lane Freeze again.
+
+Hard blocks apply only after Dev proves the current agent, branch and worktree
+belong to an active lane. Interactive or otherwise unproven sessions receive
+nudges instead. Push is blocked only when that proven lane also exposes the
+review-receipt flow; until then the hook says it cannot verify the review and
+allows the command.
+
+Codex trusts system-managed hooks without a per-hash prompt. `--system` writes
+the repository harness normally and refreshes the user-owned dispatcher under
+`~/.config/nodii-dev/codex-managed-hooks`, then only prints the one-time
+`sudo install` commands an operator can review and run to place its stable
+policy in `/etc/codex/requirements.toml`; nodii-dev never runs sudo itself.
+That system layer covers both `CODEX_HOME=~/.codex` and
+`CODEX_HOME=~/.codex-work`; later `--system` updates need no sudo. The
+dispatcher records the absolute executable path so hook processes never
+depend on `PATH`, and refreshes it on every update. Outside a lane, or when
+that executable is missing or too old, it fails open without diagnostics;
+`doctor` reports that fail-open state for each Codex profile.
 
 Until Dev exposes a lane's owned paths (AGENT-HARNESS-10), an edit with no
 ownership field emits a nudge instead of claiming it is safe or blocking an
@@ -603,11 +624,14 @@ OAuth login.
 `harness install` writes the repository's agent harness as Dev generates it
 from the ratified methodology: the `CLAUDE.md` and `AGENTS.md` pointer
 blocks, one pointer skill per methodology document, the Claude Code hooks
-merged into `.claude/settings.json`, and Dev's `.nodii/harness.json`. Every
+merged into `.claude/settings.json`, their Codex equivalents merged into
+`.codex/hooks.json`, and Dev's `.nodii/harness.json`. Every
 generated file carries the methodology version it came from. Nothing about
 the rules is authored locally. Run it in the service's own repository: it
-installs one service at a time, and there is no fleet mode. `--include-drafts`
-uses draft methodology while none is ratified.
+installs one service at a time, and there is no fleet mode. While no
+methodology is ratified, install and update automatically retry with the
+latest draft versions and print the exact draft methodology and source
+versions they used. `--include-drafts` requests that behavior explicitly.
 
 The CLI records what it wrote in `.nodii/harness-state.json` and never touches
 anything else. An existing file it did not write is refused, unless the
@@ -655,6 +679,8 @@ exits 0 only when every check is `OK`. `--json` returns the same checks as
 | `lane_limit` | The agent's active lanes against its lane limit. A full limit is `OK` when a lane on this branch holds the slot. |
 | `figma_file` | Only with `--figma-file KEY` (a key or figma.com link), or `NODII_DEV_FIGMA_FILE`: whether Dev has the brief's Figma file registered. `MISSING` names the `figma file add` command, since `figma lock` would fail with `DESIGN_FILE_NOT_FOUND`. |
 | `figma_scopes` | With `figma_file`, when the file is registered: the change set this agent holds in the file and its lock scopes (or the whole file), or that it holds none (DEC-0032). |
+| `hooks_claude` | Whether Claude hooks are installed, trusted by that runtime, and have a private firing receipt. |
+| `hooks_codex_personal`, `hooks_codex_work` | For `~/.codex` and `~/.codex-work`, whether Codex's own hook registry reports the hooks installed and trusted (including managed status), whether the managed absolute CLI is present and new enough, and whether that profile has fired one. |
 
 Doctor may refresh the access token, as any command does. The permission table
 is kept by hand from Dev's route policy until Dev's OpenAPI names each
@@ -671,9 +697,9 @@ serves for that step (see Rule delivery). Server refusals,
 including operator-only actions, workflow blocks, lane limits and Built items
 that are not on dev, retain Dev's error code/message and exit non-zero.
 
-`setup` installs the Claude Code workflow harness in the current repository.
+`setup` installs the Claude Code and Codex workflow harnesses in the current repository.
 It writes `.claude/skills/nodii-build-workflow/SKILL.md`, merges SessionStart,
-Stop and Bash PostToolUse hooks into `.claude/settings.json`, and maintains one
+Stop and tool hooks into `.claude/settings.json` and `.codex/hooks.json`, and maintains one
 marked section in an existing `CLAUDE.md` or `AGENTS.md` (creating `CLAUDE.md`
 when neither exists). Existing settings and hooks are preserved. The default
 is a read-only preview; `--yes` applies, and `--check` is suitable for drift

package/dist/cli.js

@@ -20,11 +20,12 @@ import {
   refuseFromLane,
   revokeOAuth,
 } from "./oauth.js";
-import { heartbeatCurrentLane, postHook, postHookFailure, preHook, settingsSnippet, workflowSuggestion } from "./hooks.js";
+import { heartbeatCurrentLane, postHook, postHookFailure, preHook, sessionStartContext, settingsSnippet, workflowSuggestion } from "./hooks.js";
 import { setupCommand } from "./setup.js";
 import { harnessCommand } from "./harness.js";
-import { safetyPostHook, safetyPreHook } from "./safety.js";
+import { hookRuntime, recordHookFire, safetyPostHook, safetyPreHook } from "./safety.js";
 import { doctorCommand } from "./doctor.js";
+import { dispatchManagedHook } from "./managed-hooks.js";
 import {
   figmaChangeSetShow,
   figmaChangeSetText,
@@ -120,9 +121,10 @@ Usage: nodii-dev <command> [options] [--json]
   figma changeset show CHANGE_SET       # items, variants, round, decision and comment (with the previous round's)
   figma file add FILE_KEY --name TEXT --kind design-system|surfaces|prototype [--module M]
                                         # register a Figma file in Dev so it can be locked
-  hook claude-figma-pre|claude-figma-post|safety-pre|safety-post|print-settings
+  hook claude-figma-pre|claude-figma-post|safety-pre|safety-post|session-start|managed-dispatch|print-settings
   setup [--yes|--check]                 # dry-run by default
-  harness install|update [--include-drafts[=false]] [--adopt PATH,...] [--dry-run]
+  harness install|update [--include-drafts[=false]] [--adopt PATH,...] [--dry-run] [--system]
+                                        # --system stages managed hooks and only prints operator-reviewed sudo commands
   harness check                         # 0 current, 1 differs from Dev, 2 not installed
   harness update --check                # the same check
   docs check|validate|upload <path...> --class ruling|conformance|editorial
@@ -757,15 +759,28 @@ export async function main(argv = process.argv.slice(2)) {
   if (command === "hook") {
     if (action === "print-settings")
       return console.log(JSON.stringify(settingsSnippet(), null, 2));
-    if (action === "claude-figma-pre") {
-      // Fail closed: Claude Code only blocks a tool call on exit code 2, and
-      // treats any other non-zero exit as a non-blocking error that lets the
-      // write through. Every failure here (bad stdin, missing config, Dev
-      // error, lock denied) must therefore exit 2.
+    if (action === "managed-dispatch") {
+      if (!rest[0] || rest.length > 1) throw new CliError("USAGE", "hook managed-dispatch needs one event name", 2);
+      const output = await dispatchManagedHook(rest[0], await stdinText());
+      if (output) process.stdout.write(output);
+      return;
+    }
+    if (["claude-figma-pre", "figma-pre"].includes(action)) {
+      let payload;
       try {
-        const payload = JSON.parse(await stdinText());
-        return emit(await preHook(payload), json, "allowed");
+        payload = JSON.parse(await stdinText());
+        await recordHookFire(payload).catch(() => {});
+        const result = await preHook(payload);
+        if (hookRuntime(payload) !== "codex") return emit(result, json, "allowed");
+        return;
       } catch (error) {
+        // A known policy denial still blocks. Hook/runtime failures fail open
+        // and stay silent so a broken environment cannot stop the session.
+        if (!["FIGMA_FILE_KEY_MISSING", "FIGMA_LOCK_DENIED"].includes(error?.code)) return;
+        if (payload && hookRuntime(payload) === "codex") {
+          console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: `Blocked Figma write: ${error?.message ?? String(error)}` } }));
+          return;
+        }
         throw new CliError(
           error?.code ?? "FIGMA_HOOK_FAILED",
           `Blocked Figma write: ${error?.message ?? String(error)}`,
@@ -775,12 +790,24 @@ export async function main(argv = process.argv.slice(2)) {
       }
     }
     if (action === "safety-pre") {
-      // A malformed or unavailable safety check must not turn into permission.
+      let payload;
       try {
-        const result = await safetyPreHook(JSON.parse(await stdinText()));
-        for (const nudge of result.nudges ?? []) console.log(nudge);
+        payload = JSON.parse(await stdinText());
+        await recordHookFire(payload).catch(() => {});
+        const result = await safetyPreHook(payload);
+        const nudges = result.nudges ?? [];
+        if (nudges.length && hookRuntime(payload) === "codex")
+          console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: nudges.join("\n") } }));
+        else for (const nudge of nudges) console.log(nudge);
         return;
       } catch (error) {
+        // Only an evaluated safety rule may deny. Discovery, parsing, git,
+        // config and Dev errors fail open and produce no output.
+        if (!String(error?.code ?? "").startsWith("SAFETY_")) return;
+        if (payload && hookRuntime(payload) === "codex") {
+          console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: error?.message ?? String(error) } }));
+          return;
+        }
         throw new CliError(
           error?.code ?? "SAFETY_HOOK_FAILED",
           error?.message ?? String(error),
@@ -790,13 +817,12 @@ export async function main(argv = process.argv.slice(2)) {
       }
     }
     if (action === "safety-post") {
+      let payload;
       try {
-        await safetyPostHook(JSON.parse(await stdinText()));
-      } catch (error) {
-        // A post-hook cannot undo a completed command; report state-tracking
-        // failure without making Claude treat the completed command as failed.
-        console.error(`nodii-dev safety post hook: ${error?.code ?? "ERROR"}: ${error?.message ?? String(error)}`);
-      }
+        payload = JSON.parse(await stdinText());
+        await recordHookFire(payload).catch(() => {});
+        await safetyPostHook(payload);
+      } catch {}
       return;
     }
     if (action === "lane-heartbeat") {
@@ -804,18 +830,31 @@ export async function main(argv = process.argv.slice(2)) {
       return emit(result, json, result.heartbeated ? `Heartbeat recorded for ${result.key}.` : "No current-branch lane; no heartbeat sent.");
     }
     const payload = JSON.parse(await stdinText());
+    await recordHookFire(payload).catch(() => {});
+    if (action === "session-start") {
+      const context = await sessionStartContext(payload);
+      if (context) console.log(context);
+      return;
+    }
     if (action === "workflow-post") {
       const suggestion = workflowSuggestion(payload);
-      if (suggestion) console.log(suggestion);
+      if (suggestion && hookRuntime(payload) === "codex")
+        console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: suggestion } }));
+      else if (suggestion) console.log(suggestion);
       return;
     }
-    if (action === "claude-figma-post") {
+    if (["claude-figma-post", "figma-post"].includes(action)) {
       try {
         return emit(await postHook(payload), json, "logged");
       } catch (error) {
         const outcome = postHookFailure(error);
-        console.error(outcome.message);
-        if (outcome.exitCode) process.exitCode = outcome.exitCode;
+        if (!outcome.exitCode) return;
+        if (hookRuntime(payload) === "codex")
+          console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: outcome.message } }));
+        else {
+          console.error(outcome.message);
+          if (outcome.exitCode) process.exitCode = outcome.exitCode;
+        }
         return;
       }
     }

package/dist/core.js

@@ -4,7 +4,7 @@ import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 
-export const VERSION = "0.6.25";
+export const VERSION = "0.6.27";
 export const configPath = () =>
   process.env.NODII_DEV_CONFIG_PATH ??
   join(homedir(), ".config/nodii-dev/config.json");
@@ -199,7 +199,7 @@ export async function checkLogin() {
 export const encode = (value) => encodeURIComponent(value);
 // Switches never take the next token as their value, so
 // `docs upload --wait rulebook/` keeps rulebook/ as a path.
-const SWITCHES = new Set(["json", "wait", "dry-run", "check", "all", "fleet", "help", "yes", "mine", "no-browser", "include-drafts", "drafted", "library", "async", "sync", "force"]);
+const SWITCHES = new Set(["json", "wait", "dry-run", "check", "all", "fleet", "help", "yes", "mine", "no-browser", "include-drafts", "drafted", "library", "async", "sync", "force", "system"]);
 export function parseArgs(argv) {
   const flags = {};
   const args = [];

package/dist/doctor.js

@@ -5,6 +5,7 @@ import { devRequest, encode, isOAuthConfig, query, setAuthProvider } from "./cor
 import { OAuthAuthProvider, decodeClaims, loadRefreshToken } from "./oauth.js";
 import { inferGitContext, repoName } from "./lanes.js";
 import { figmaFileKey, figmaLockCheck, holdsSet, notRegisteredHint, scopeText } from "./figma.js";
+import { hookDiagnostics } from "./hook-doctor.js";
 
 /**
  * What a lane's commands need, in Dev's route policy (staffRuleFor in Dev's
@@ -262,6 +263,25 @@ export async function doctorCommand(deps = {}) {
     }
   }
 
+  // 9. Runtime hooks: present, accepted by that runtime, and observed firing.
+  const hookRoot = context?.worktree ?? deps.cwd ?? process.cwd();
+  try {
+    const runtimes = await (deps.hookDiagnostics ?? hookDiagnostics)(hookRoot);
+    for (const runtime of runtimes) {
+      const key = `hooks_${runtime.runtime.replace(/[^a-z0-9]+/gi, "_")}`;
+      const extra = { runtime: runtime.runtime, installed: runtime.installed, trusted: runtime.trusted, firing: runtime.firing, managed: runtime.managed, lastFiredAt: runtime.lastFiredAt ?? null, ...(runtime.cliStatus ? { cliStatus: runtime.cliStatus } : {}) };
+      if (runtime.installed === null) checks.push(cannot(key, runtime.error ?? "runtime hook registry unavailable", extra));
+      else if (!runtime.installed) checks.push(missing(key, "hooks are not installed", "nodii-dev harness install (or setup --yes)", extra));
+      else if (!runtime.trusted) checks.push(missing(key, `hooks are installed but not trusted${runtime.trustStatuses?.length ? ` (${runtime.trustStatuses.join(", ")})` : ""}`, runtime.runtime.startsWith("codex") ? "review /hooks, or have an operator run the commands printed by `nodii-dev harness update --system`" : "review the runtime hook configuration", extra));
+      else if (runtime.managed && runtime.cliStatus?.ok === false) checks.push(missing(key, `${runtime.cliStatus.message}; managed hooks fail open until this is fixed`, "update nodii-dev, then run `nodii-dev harness update --system` to refresh the absolute CLI path", extra));
+      else if (!runtime.firing) checks.push(missing(key, `hooks are installed and trusted${runtime.managed ? " (managed)" : ""}, but no firing receipt exists`, "start a fresh runtime session and run doctor again", extra));
+      else checks.push(ok(key, `installed, trusted${runtime.managed ? " (managed)" : ""}, and firing (last ${runtime.lastFiredAt})`, extra));
+    }
+  } catch (error) {
+    checks.push(cannot("hooks_claude", error?.message ?? String(error)));
+    checks.push(cannot("hooks_codex", error?.message ?? String(error)));
+  }
+
   const ready = checks.every((x) => x.status === "ok");
   const width = Math.max(...checks.map((x) => x.key.length));
   const human = (p) => [

package/dist/harness.js

@@ -7,9 +7,11 @@ import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join, normalize, sep } from "node:path";
+import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { CliError, devRequest, query } from "./core.js";
-import { safetySettingsSnippet } from "./safety.js";
+import { managedHookBundle, nodiiCommandArgs, writeManagedHookBundle } from "./managed-hooks.js";
+import { codexSafetyHooksSnippet, regroundingHooksSnippet, safetySettingsSnippet } from "./safety.js";
 
 /** What this CLI wrote, per path: { mode, sha256 }, or for merge-json the hook entries it `added`. */
 export const STATE_PATH = ".nodii/harness-state.json";
@@ -35,7 +37,7 @@ async function optional(path) {
 
 // The only files Dev generates (AD-era contract §7). Anything else, such as a
 // git hook or a CI workflow, is refused whatever the disk's case rules.
-const HARNESS_PATHS = [/^CLAUDE\.md$/, /^AGENTS\.md$/, /^\.claude\/settings\.json$/, /^\.nodii\/harness\.json$/, /^\.claude\/skills\/nodii-[a-z0-9][a-z0-9._-]*\/SKILL\.md$/];
+const HARNESS_PATHS = [/^CLAUDE\.md$/, /^AGENTS\.md$/, /^\.claude\/settings\.json$/, /^\.codex\/hooks\.json$/, /^\.nodii\/harness\.json$/, /^\.claude\/skills\/nodii-[a-z0-9][a-z0-9._-]*\/SKILL\.md$/];
 
 /** A generated path must be one of the harness files the contract names. */
 export function safeRelative(path) {
@@ -142,9 +144,47 @@ export function checkHarness(harness) {
   });
 }
 
+const CODEX_EVENTS = new Set([
+  "SessionStart", "UserPromptSubmit", "PreToolUse", "PermissionRequest", "PostToolUse",
+  "PreCompact", "PostCompact", "SubagentStart", "SubagentStop", "Stop", "Interrupt", "SessionEnd",
+]);
+
+function addHookEntries(hooks, additions) {
+  const out = { ...hooks };
+  for (const [event, entries] of Object.entries(additions ?? {})) {
+    out[event] = [...(out[event] ?? [])];
+    for (const entry of entries) if (!out[event].some((existing) => stable(existing) === stable(entry))) out[event].push(entry);
+  }
+  return out;
+}
+
+function assertNodiiHooks(hooks, path) {
+  for (const [event, entries] of Object.entries(hooks ?? {}))
+    for (const entry of entries)
+      for (const handler of entry.hooks ?? [])
+        if (handler.type !== "command")
+          throw new CliError("HARNESS_INVALID", `${path} ${event} hooks may run nodii-dev commands only (MW5-20).`, 1);
+        else try { nodiiCommandArgs(handler.command); }
+        catch { throw new CliError("HARNESS_INVALID", `${path} ${event} hooks may run one nodii-dev command only (MW5-20).`, 1); }
+}
+
+export function codexHooksFromClaude(hooks = {}) {
+  const out = {};
+  for (const [event, entries] of Object.entries(hooks)) {
+    if (!CODEX_EVENTS.has(event)) continue;
+    out[event] = entries.map((entry) => {
+      if (!["PreToolUse", "PermissionRequest", "PostToolUse"].includes(event) || !entry.matcher) return structuredClone(entry);
+      const translated = entry.matcher.replace(/\b(?:Edit|Write|MultiEdit|NotebookEdit)\b/g, "apply_patch");
+      const matcher = translated.replace(/\|apply_patch(?=(?:\|apply_patch)+\))/g, "");
+      return { ...structuredClone(entry), matcher };
+    });
+  }
+  return out;
+}
+
 // Safety enforcement is executable CLI behaviour, not methodology prose. Add
-// its nodii-dev-only hook entries to the settings fragment Dev generated so a
-// normal harness install/update always installs the matching CLI hooks.
+// its nodii-dev-only entries for both runtimes. Codex receives the same
+// lifecycle blocks with runtime-specific tool matchers.
 export function withSafetyHooks(harness) {
   checkHarness(harness);
   const copy = { ...harness, files: harness.files.map((file) => ({ ...file })) };
@@ -156,13 +196,25 @@ export function withSafetyHooks(harness) {
   if (settings.mode !== "merge-json")
     throw new CliError("HARNESS_INVALID", "Dev must generate .claude/settings.json as merge-json so nodii-dev can install safety hooks.", 1);
   const parsed = JSON.parse(settings.content);
-  const hooks = { ...(parsed.hooks ?? {}) };
-  for (const [event, entries] of Object.entries(safetySettingsSnippet().hooks)) {
-    hooks[event] = [...(hooks[event] ?? [])];
-    for (const entry of entries) if (!hooks[event].some((existing) => stable(existing) === stable(entry))) hooks[event].push(entry);
-  }
+  let hooks = addHookEntries(parsed.hooks, safetySettingsSnippet().hooks);
+  hooks = addHookEntries(hooks, regroundingHooksSnippet().hooks);
+  assertNodiiHooks(hooks, ".claude/settings.json");
   settings.content = JSON.stringify({ ...parsed, hooks });
   settings.sha256 = sha(settings.content);
+
+  let codex = copy.files.find((file) => file.path === ".codex/hooks.json");
+  if (!codex) {
+    codex = { path: ".codex/hooks.json", mode: "merge-json", kind: "settings", content: "{}" };
+    copy.files.push(codex);
+  }
+  if (codex.mode !== "merge-json")
+    throw new CliError("HARNESS_INVALID", "Dev must generate .codex/hooks.json as merge-json so nodii-dev can install Codex hooks.", 1);
+  const codexParsed = JSON.parse(codex.content);
+  let codexHooks = addHookEntries(codexParsed.hooks, codexHooksFromClaude(hooks));
+  codexHooks = addHookEntries(codexHooks, codexSafetyHooksSnippet().hooks);
+  assertNodiiHooks(codexHooks, ".codex/hooks.json");
+  codex.content = JSON.stringify({ ...codexParsed, hooks: codexHooks });
+  codex.sha256 = sha(codex.content);
   return copy;
 }
 
@@ -181,7 +233,7 @@ export async function planHarness(root, harness, { install, adopt = [], request
   const owned = state?.files ?? {};
   const adopted = new Set(adopt.map((path) => {
     try { return safeRelative(path); }
-    catch { throw new CliError("USAGE", `--adopt ${path} is not a harness file (CLAUDE.md, AGENTS.md, .claude/settings.json, .claude/skills/nodii-CODE/SKILL.md).`, 2); }
+    catch { throw new CliError("USAGE", `--adopt ${path} is not a harness file (CLAUDE.md, AGENTS.md, .claude/settings.json, .codex/hooks.json, .claude/skills/nodii-CODE/SKILL.md).`, 2); }
   }));
   const changes = [];
   const conflicts = [];
@@ -315,6 +367,21 @@ export async function repoContext(cwd = process.cwd()) {
 const flagList = (value) => (value === undefined || value === true ? [] : [value].flat().flatMap((x) => String(x).split(",")).filter(Boolean));
 const changeLine = (c) => `${{ create: "+", remove: "-" }[c.action] ?? "~"} ${c.path}${["create", "update", "remove"].includes(c.action) ? "" : ` (${c.action})`}`;
 
+const shellQuote = (value) => `'${String(value).replaceAll("'", `'\\''`)}'`;
+
+/**
+ * Print-only operator plan for the managed Codex layer. The CLI deliberately
+ * never invokes sudo: an operator reviews the generated hooks before copying
+ * the exact repository file into Codex's trusted system layer.
+ */
+export function systemHookInstallPlan(bundle) {
+  const source = join(bundle.dir, "requirements.toml");
+  return [
+    "sudo install -d -m 0755 /etc/codex",
+    `sudo install -m 0644 ${shellQuote(source)} /etc/codex/requirements.toml`,
+  ];
+}
+
 // What each planned change means for a check: how the file on disk differs from Dev's.
 const DIFFERENCE = {
   create: "missing; Dev would create it",
@@ -370,8 +437,8 @@ async function checkCommand(root, repo, state, fetchHarness) {
   };
 }
 
-export async function harnessCommand(action, flags, { request = devRequest, context = repoContext } = {}) {
-  if (!["install", "update", "check"].includes(action)) throw new CliError("USAGE", "harness install|update|check [--repo NAME] [--service ID] [--include-drafts[=false]] [--adopt PATH,...] [--dry-run] [--check]", 2);
+export async function harnessCommand(action, flags, { request = devRequest, context = repoContext, managedHome, managedCliPath = fileURLToPath(new URL("../bin/nodii-dev", import.meta.url)), writeManaged = writeManagedHookBundle } = {}) {
+  if (!["install", "update", "check"].includes(action)) throw new CliError("USAGE", "harness install|update|check [--repo NAME] [--service ID] [--include-drafts[=false]] [--adopt PATH,...] [--dry-run] [--check] [--system]", 2);
   if (flags.fleet || flags.all) throw new CliError("USAGE", "The harness is installed one service at a time, in that service's repository. There is no fleet mode.", 2);
   if (flags.root === true || flags.repo === true) throw new CliError("USAGE", "--root and --repo need a value.", 2);
   const ctx = flags.root ? { root: flags.root, repo: flags.repo } : await context();
@@ -382,18 +449,33 @@ export async function harnessCommand(action, flags, { request = devRequest, cont
   const saved = action === "install" ? {} : (state?.request ?? {});
   const serviceId = flags.service && flags.service !== true ? String(flags.service) : (saved.serviceId ?? undefined);
   const includeDrafts = flags["include-drafts"] !== undefined ? flags["include-drafts"] !== "false" : Boolean(saved.includeDrafts);
-  const params = { repo, serviceId, includeDrafts: includeDrafts ? "true" : undefined };
-  const fetchHarness = async () => {
-    const response = await request("GET", `/api/v1/harness${query(params)}`);
-    return { ...response, data: withSafetyHooks(response.data) };
+  let effectiveIncludeDrafts = includeDrafts;
+  const fetchHarness = async ({ draftFallback = false } = {}) => {
+    const get = () => request("GET", `/api/v1/harness${query({ repo, serviceId, includeDrafts: effectiveIncludeDrafts ? "true" : undefined })}`);
+    let response;
+    let fallback = false;
+    try { response = await get(); }
+    catch (error) {
+      if (!draftFallback || effectiveIncludeDrafts || error?.code !== "METHODOLOGY_NOT_AVAILABLE") throw error;
+      effectiveIncludeDrafts = true;
+      fallback = true;
+      response = await get();
+    }
+    const sources = response.data?.sources ?? [];
+    const draftSources = sources.filter((source) => source.status !== "ratified");
+    const draftNotice = draftSources.length
+      ? `${fallback || draftSources.length === sources.length ? "No methodology is ratified; using latest draft methodology" : "Using draft methodology"} ${response.data.methodologyVersion} (${draftSources.map((source) => `${source.code} ${source.version}`).join(", ")}).`
+      : null;
+    const data = draftNotice ? { ...response.data, warnings: [...(response.data.warnings ?? []), draftNotice] } : response.data;
+    return { ...response, data: withSafetyHooks(data) };
   };
 
   if (action === "install" && flags.check) throw new CliError("USAGE", "--check goes with `harness update`; to preview an install use --dry-run.", 2);
-  if (action === "check" && (flags["dry-run"] || flags.adopt)) throw new CliError("USAGE", "harness check writes nothing; --dry-run and --adopt go with install and update.", 2);
+  if (action === "check" && (flags["dry-run"] || flags.adopt || flags.system)) throw new CliError("USAGE", "harness check writes nothing; --dry-run, --adopt and --system go with install and update.", 2);
   if (action === "check" || (action === "update" && flags.check)) return checkCommand(ctx.root, repo, state, fetchHarness);
 
-  const harness = (await fetchHarness()).data;
-  const plan = await planHarness(ctx.root, harness, { install: action === "install", adopt: flagList(flags.adopt), request: { ...(serviceId ? { serviceId } : {}), includeDrafts } });
+  const harness = (await fetchHarness({ draftFallback: true })).data;
+  const plan = await planHarness(ctx.root, harness, { install: action === "install", adopt: flagList(flags.adopt), request: { ...(serviceId ? { serviceId } : {}), includeDrafts: effectiveIncludeDrafts } });
   const summary = {
     repo: harness.repo, serviceId: harness.serviceId ?? null,
     from: state?.methodologyVersion ?? null, to: harness.methodologyVersion,
@@ -411,7 +493,18 @@ export async function harnessCommand(action, flags, { request = devRequest, cont
     throw new CliError("HARNESS_CONFLICT",
       `Nothing written. These files are not nodii-dev's to change:\n${plan.conflicts.map((c) => `  ${c.path}: ${c.reason}`).join("\n")}\n` +
       "Restore files nodii-dev wrote (git checkout, or remove your edits). For your own files, remove them or let nodii-dev take them over with --adopt PATH[,PATH].", 1, summary);
-  if (flags["dry-run"]) return { payload: { data: { ...summary, dryRun: true } }, human: `${lines.join("\n")}\n${plan.changes.length ? "Dry run: nothing written." : "No changes."}` };
+  const codexChange = plan.changes.find((change) => change.path === ".codex/hooks.json");
+  const codexText = codexChange?.text ?? await optional(join(ctx.root, ".codex/hooks.json"));
+  const managedBundle = flags.system ? managedHookBundle(codexText, { home: managedHome, cliPath: managedCliPath }) : null;
+  const systemCommands = managedBundle ? systemHookInstallPlan(managedBundle) : [];
+  if (flags["dry-run"]) {
+    const preview = managedBundle ? `\nWould stage managed Codex hooks in ${managedBundle.dir}. Dry run: no managed files were written and no sudo commands are printed until they exist.` : "";
+    return { payload: { data: { ...summary, dryRun: true, ...(managedBundle ? { managedDir: managedBundle.dir } : {}) } }, human: `${lines.join("\n")}\n${plan.changes.length ? "Dry run: nothing written." : "No changes."}${preview}` };
+  }
+  const systemText = systemCommands.length
+    ? `\nManaged Codex hooks are staged in ${managedBundle.dir}. One operator install covers codex-personal and codex-work; review ${join(managedBundle.dir, "requirements.toml")}, then run:\n${systemCommands.join("\n")}\nNo privileged command was run. Later --system updates refresh the user-owned managed directory without sudo.`
+    : "";
   await applyHarness(ctx.root, plan);
-  return { payload: { data: { ...summary, applied: true } }, human: `${lines.join("\n")}\n${plan.changes.length ? `${action === "install" ? "Installed" : "Updated"}: ${plan.changes.length} change${plan.changes.length === 1 ? "" : "s"}.` : "Harness already current."}` };
+  if (managedBundle) await writeManaged(managedBundle);
+  return { payload: { data: { ...summary, applied: true, ...(systemCommands.length ? { systemCommands, managedDir: managedBundle.dir } : {}) } }, human: `${lines.join("\n")}\n${plan.changes.length ? `${action === "install" ? "Installed" : "Updated"}: ${plan.changes.length} change${plan.changes.length === 1 ? "" : "s"}.` : "Harness already current."}${systemText}` };
 }

package/dist/hook-doctor.js

@@ -0,0 +1,126 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { readFile, rm, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { HOOK_EVENTS } from "./safety.js";
+import { managedHookCliStatus } from "./managed-hooks.js";
+
+const execFileAsync = promisify(execFile);
+
+async function optional(path) {
+  try { return await readFile(path, "utf8"); }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+
+const nodiiEntries = (hooks = {}) => Object.values(hooks).flat().filter((entry) =>
+  (entry.hooks ?? []).some((hook) => hook.type === "command" && /^nodii-dev(?:\s|$)/.test(String(hook.command ?? ""))),
+);
+
+async function firingEvents(root) {
+  try {
+    const path = (await execFileAsync("git", ["-C", root, "rev-parse", "--path-format=absolute", "--git-path", HOOK_EVENTS], { encoding: "utf8" })).stdout.trim();
+    const text = await optional(path);
+    return String(text ?? "").trim().split("\n").filter(Boolean).flatMap((line) => {
+      try { return [JSON.parse(line)]; } catch { return []; }
+    });
+  } catch { return []; }
+}
+
+/** Read the hook registry Codex itself resolved for this cwd. */
+export function codexHooksList(cwd, { codexBin = "codex", spawnImpl = spawn, timeoutMs = 5_000, env = process.env } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawnImpl(codexBin, ["app-server", "--stdio"], { cwd, env, stdio: ["pipe", "pipe", "pipe"] });
+    const pidFile = join(tmpdir(), `nodii-dev-codex-hooks-${child.pid ?? "starting"}-${randomUUID()}.pid`);
+    let stdout = "";
+    let stderr = "";
+    let listed = null;
+    let settled = false;
+    let forceTimer;
+    let pidSaved = Promise.reject(new Error("Codex process did not start"));
+    pidSaved.catch(() => {});
+    const cleanup = async () => { clearTimeout(timer); clearTimeout(forceTimer); await rm(pidFile, { force: true }).catch(() => {}); };
+    const finish = async (error) => {
+      if (settled) return;
+      settled = true;
+      await cleanup();
+      if (error) reject(error); else resolve(listed ?? []);
+    };
+    const send = (value) => child.stdin.write(`${JSON.stringify(value)}\n`);
+    const timer = setTimeout(() => {
+      child.stdin.end();
+      forceTimer = setTimeout(async () => {
+        try { await pidSaved; child.kill("SIGTERM"); } catch {}
+      }, 1_000);
+    }, timeoutMs);
+    child.on("spawn", () => { pidSaved = writeFile(pidFile, `${child.pid}\n`, { mode: 0o600 }); pidSaved.catch(() => {}); });
+    child.on("error", (error) => finish(error));
+    child.stderr.on("data", (chunk) => { if (stderr.length < 4_096) stderr += chunk; });
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+      for (;;) {
+        const newline = stdout.indexOf("\n");
+        if (newline < 0) break;
+        const line = stdout.slice(0, newline);
+        stdout = stdout.slice(newline + 1);
+        if (!line) continue;
+        let message;
+        try { message = JSON.parse(line); } catch { continue; }
+        if (message.id === 1) {
+          send({ method: "initialized", params: {} });
+          send({ id: 2, method: "hooks/list", params: { cwd } });
+        } else if (message.id === 2) {
+          if (message.error) { child.stdin.end(); finish(new Error(message.error.message ?? "Codex hooks/list failed")); return; }
+          listed = message.result?.data ?? [];
+          child.stdin.end();
+        }
+      }
+    });
+    child.on("exit", (code) => {
+      if (listed) finish();
+      else finish(new Error(`codex app-server exited ${code ?? "without a status"}${stderr.trim() ? `: ${stderr.trim()}` : ""}`));
+    });
+    send({ id: 1, method: "initialize", params: { clientInfo: { name: "nodii-dev-doctor-probe", title: "nodii-dev doctor probe", version: "0.0.0" } } });
+  });
+}
+
+export async function hookDiagnostics(root, deps = {}) {
+  const events = await (deps.firingEvents ?? firingEvents)(root);
+  const fired = (runtime) => events.filter((event) => event.runtime === runtime || event.profile === runtime).at(-1) ?? null;
+  let claude = {};
+  try { claude = JSON.parse((await optional(join(root, ".claude/settings.json"))) ?? "{}"); }
+  catch { claude = {}; }
+  const claudeInstalled = nodiiEntries(claude.hooks).length > 0;
+  const out = [{
+    runtime: "claude", installed: claudeInstalled, trusted: claudeInstalled,
+    firing: Boolean(fired("claude")), lastFiredAt: fired("claude")?.at ?? null,
+    managed: false,
+  }];
+  const profiles = deps.codexProfiles ?? [
+    { runtime: "codex-personal", home: join(homedir(), ".codex") },
+    { runtime: "codex-work", home: join(homedir(), ".codex-work") },
+  ];
+  const cliStatus = await (deps.managedHookCliStatus ?? managedHookCliStatus)({ home: deps.home ?? homedir() });
+  for (const profile of profiles) {
+    try {
+      const data = await (deps.codexHooksList ?? codexHooksList)(root, { ...deps, env: { ...(deps.env ?? process.env), CODEX_HOME: profile.home } });
+      const record = data.find((item) => item.cwd === root) ?? data[0] ?? {};
+      const hooks = record.hooks ?? [];
+      const managedHooks = hooks.filter((hook) => hook.isManaged === true || hook.trustStatus === "managed");
+      const trustedHooks = hooks.filter((hook) => hook.isManaged === true || ["managed", "trusted"].includes(hook.trustStatus));
+      out.push({
+        runtime: profile.runtime, profileHome: profile.home, installed: hooks.length > 0, trusted: managedHooks.length > 0 || (hooks.length > 0 && trustedHooks.length === hooks.length),
+        firing: Boolean(fired(profile.runtime)), lastFiredAt: fired(profile.runtime)?.at ?? null,
+        managed: managedHooks.length > 0, managedCount: managedHooks.length,
+        ...(managedHooks.length ? { cliStatus } : {}),
+        trustStatuses: [...new Set(hooks.map((hook) => hook.trustStatus ?? "unknown"))],
+        warnings: record.warnings ?? [], errors: record.errors ?? [],
+      });
+    } catch (error) {
+      out.push({ runtime: profile.runtime, profileHome: profile.home, installed: null, trusted: null, firing: Boolean(fired(profile.runtime)), lastFiredAt: fired(profile.runtime)?.at ?? null, managed: null, error: error.message });
+    }
+  }
+  return out;
+}

package/dist/hooks.js

@@ -1,6 +1,8 @@
-import { CliError, devRequest } from "./core.js";
+import { CliError, devRequest, readConfig } from "./core.js";
 import { FOUNDATIONS_ID, figmaLockCheck, outOfScopeText } from "./figma.js";
 import { execFile } from "node:child_process";
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
 import { promisify } from "node:util";
 import { safetySettingsSnippet } from "./safety.js";
 
@@ -214,6 +216,34 @@ export async function heartbeatCurrentLane(request = devRequest) {
   return { heartbeated: true, key: lane.key };
 }
 
+/** SessionStart compact context, plain text for both Claude and Codex. */
+export async function sessionStartContext(payload, { request = devRequest, config = readConfig } = {}) {
+  if (payload?.source !== "compact") return null;
+  let lane = null;
+  try {
+    const cwd = payload.cwd ?? process.cwd();
+    const branch = (await execFileAsync("git", ["branch", "--show-current"], { cwd, encoding: "utf8" })).stdout.trim();
+    const rootText = (await execFileAsync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8" })).stdout.trim();
+    const root = await realpath(rootText).catch(() => resolve(rootText));
+    const current = await config(false);
+    const lanes = (await request("GET", "/api/v1/lanes?limit=200")).data ?? [];
+    for (const item of lanes) {
+      if (item.agentId !== current.agentId || item.branch !== branch || ["on_dev", "stopped"].includes(item.status)) continue;
+      const worktree = await realpath(item.worktree ?? root).catch(() => resolve(item.worktree ?? root));
+      if (worktree === root) { lane = item; break; }
+    }
+  } catch {}
+  if (!lane) return "Freeze re-grounding: no active Dev lane was available for this branch; re-read the lane brief before continuing.";
+  const freeze = lane.freeze ?? {};
+  return [
+    `Freeze re-grounding for ${lane.key}:`,
+    `title: ${lane.title ?? "(untitled)"}`,
+    `status: ${lane.status}`,
+    `boundaries: ${JSON.stringify(freeze.boundaries ?? {})}`,
+    `rules: ${JSON.stringify(freeze.rules ?? freeze.ruleRefs ?? [])}`,
+  ].join("\n");
+}
+
 export function workflowSuggestion(payload) {
   const command = payload?.tool_input?.command ?? "";
   if (/\bgit\s+push\b/.test(command)) return "nodii-dev: pushed work; record it with `nodii-dev lane evidence <key> --commit <sha>` or `--pr <url>`.";

package/dist/managed-hooks.js

@@ -0,0 +1,169 @@
+import { spawn } from "node:child_process";
+import { access, chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { homedir } from "node:os";
+import { basename, isAbsolute, join } from "node:path";
+import { CliError, VERSION } from "./core.js";
+
+export const CODEX_HOOK_EVENTS = [
+  "SessionStart", "UserPromptSubmit", "PreToolUse", "PermissionRequest", "PostToolUse",
+  "PreCompact", "PostCompact", "SubagentStart", "SubagentStop", "Stop", "Interrupt", "SessionEnd",
+];
+
+export const managedHooksDir = (home = homedir()) => join(home, ".config", "nodii-dev", "codex-managed-hooks");
+export const MANAGED_DISPATCH_MIN_VERSION = "0.6.27";
+
+/** Only a single nodii-dev invocation is allowed; shell composition is never accepted. */
+export function nodiiCommandArgs(command) {
+  const text = String(command ?? "").trim();
+  if (!text.startsWith("nodii-dev") || /[;&|<>`$\\\r\n]/.test(text))
+    throw new CliError("HARNESS_INVALID", `Managed hooks may run one nodii-dev command only: ${command}`, 1);
+  const words = text.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
+  if (words.shift() !== "nodii-dev") throw new CliError("HARNESS_INVALID", `Managed hooks may run nodii-dev commands only: ${command}`, 1);
+  return words.map((word) => /^(['"]).*\1$/.test(word) ? word.slice(1, -1) : word);
+}
+
+export function validateManagedHooks(hooks = {}) {
+  for (const [event, entries] of Object.entries(hooks)) {
+    if (!CODEX_HOOK_EVENTS.includes(event)) throw new CliError("HARNESS_INVALID", `Codex does not support managed hook event ${event}.`, 1);
+    for (const entry of entries)
+      for (const handler of entry.hooks ?? []) {
+        if (handler.type !== "command") throw new CliError("HARNESS_INVALID", `Managed ${event} hooks must be command handlers.`, 1);
+        nodiiCommandArgs(handler.command);
+      }
+  }
+}
+
+const tomlString = (value) => JSON.stringify(String(value));
+const shellString = (value) => `'${String(value).replaceAll("'", `'\\''`)}'`;
+const laneConfig = (env) => /^lane-[a-z0-9_-]+\.json$/i.test(basename(env.NODII_DEV_CONFIG_PATH ?? ""));
+const emptyResponse = (event) => ["Stop", "SubagentStop"].includes(event) ? "{}\n" : "";
+
+/** Stable managed policy: all later hook changes live in user-owned hooks.json. */
+export function managedRequirements(dir) {
+  const dispatcher = join(dir, "dispatch");
+  return [
+    "[features]",
+    "hooks = true",
+    "",
+    "[hooks]",
+    `managed_dir = ${tomlString(dir)}`,
+    "",
+    ...CODEX_HOOK_EVENTS.flatMap((event) => [
+      `[[hooks.${event}]]`,
+      'matcher = ".*"',
+      "",
+      `[[hooks.${event}.hooks]]`,
+      'type = "command"',
+      `command = ${tomlString(`${dispatcher} ${event}`)}`,
+      "timeout = 30",
+      'statusMessage = "Applying Nodii harness policy"',
+      "",
+    ]),
+  ].join("\n");
+}
+
+export function managedHookBundle(hooksText, { home, cliPath, cliVersion = VERSION } = {}) {
+  let parsed;
+  try { parsed = JSON.parse(String(hooksText ?? "")); }
+  catch { throw new CliError("HARNESS_SETTINGS_INVALID", ".codex/hooks.json is not valid JSON.", 2); }
+  validateManagedHooks(parsed.hooks ?? {});
+  if (!isAbsolute(String(cliPath ?? ""))) throw new CliError("HARNESS_INVALID", "The managed Codex dispatcher needs the absolute nodii-dev executable path.", 1);
+  const dir = managedHooksDir(home);
+  const command = shellString(cliPath);
+  const dispatch = `#!/bin/sh\nmanaged_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)\nmanaged_cli=${command}\nempty_response() {\n  case "$1" in Stop|SubagentStop) printf '{}\\n' ;; esac\n}\ncase "\${NODII_DEV_CONFIG_PATH##*/}" in lane-*.json) ;; *) empty_response "$1"; exit 0 ;; esac\nif [ ! -x "$managed_cli" ]; then empty_response "$1"; exit 0; fi\nexport NODII_DEV_MANAGED_HOOKS_DIR="$managed_dir"\nexport NODII_DEV_MANAGED_CLI_PATH="$managed_cli"\nmanaged_output=$("$managed_cli" hook managed-dispatch "$1" 2>/dev/null)\nmanaged_status=$?\nif [ "$managed_status" -ne 0 ]; then empty_response "$1"; exit 0; fi\nif [ -n "$managed_output" ]; then printf '%s\\n' "$managed_output"; else empty_response "$1"; fi\n`;
+  const metadata = `${JSON.stringify({ cliPath, cliVersion, minimumVersion: MANAGED_DISPATCH_MIN_VERSION }, null, 2)}\n`;
+  return { dir, hooksText: `${JSON.stringify({ hooks: parsed.hooks ?? {} }, null, 2)}\n`, dispatch, metadata, requirements: managedRequirements(dir) };
+}
+
+export async function writeManagedHookBundle(bundle) {
+  await mkdir(bundle.dir, { recursive: true, mode: 0o700 });
+  await writeFile(join(bundle.dir, "hooks.json"), bundle.hooksText, { mode: 0o600 });
+  await writeFile(join(bundle.dir, "dispatch"), bundle.dispatch, { mode: 0o700 });
+  await chmod(join(bundle.dir, "dispatch"), 0o700);
+  await writeFile(join(bundle.dir, "metadata.json"), bundle.metadata, { mode: 0o600 });
+  await writeFile(join(bundle.dir, "requirements.toml"), bundle.requirements, { mode: 0o600 });
+}
+
+function runHandler(args, input, { spawnImpl = spawn, env = process.env } = {}) {
+  return new Promise((resolve) => {
+    const child = spawnImpl(env.NODII_DEV_MANAGED_CLI_PATH ?? "nodii-dev", args, { env, stdio: ["pipe", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => { stdout += chunk; });
+    child.stderr.on("data", (chunk) => { stderr += chunk; });
+    child.on("error", (error) => resolve({ status: 1, stdout, stderr: `${stderr}${error.message}` }));
+    child.on("exit", (status) => resolve({ status: status ?? 1, stdout, stderr }));
+    child.stdin.end(input);
+  });
+}
+
+const matchTarget = (event, payload) => {
+  if (["PreToolUse", "PermissionRequest", "PostToolUse"].includes(event)) return payload.tool_name ?? "";
+  if (event === "SessionStart") return payload.source ?? "";
+  return payload.agent_type ?? payload.source ?? "";
+};
+
+function responseOf(stdout) {
+  try { return JSON.parse(stdout.trim()); } catch { return null; }
+}
+
+/** Execute the current generated hook set behind the stable managed dispatcher. */
+export async function dispatchManagedHook(event, payloadText, deps = {}) {
+  try {
+    if (!CODEX_HOOK_EVENTS.includes(event)) return emptyResponse(event);
+    const env = deps.env ?? process.env;
+    if (!laneConfig(env)) return emptyResponse(event);
+    const dir = deps.dir ?? env.NODII_DEV_MANAGED_HOOKS_DIR ?? managedHooksDir();
+    const config = JSON.parse(await (deps.read ?? readFile)(join(dir, "hooks.json"), "utf8"));
+    validateManagedHooks(config.hooks ?? {});
+    const payload = JSON.parse(payloadText);
+    const target = matchTarget(event, payload);
+    const handlers = (config.hooks?.[event] ?? []).filter((entry) => {
+      try { return new RegExp(entry.matcher || ".*").test(target); } catch { return false; }
+    }).flatMap((entry) => entry.hooks ?? []);
+    const results = await Promise.all(handlers.map((handler) => (deps.run ?? runHandler)(nodiiCommandArgs(handler.command), payloadText, deps)));
+    // A failed handler is unavailable policy, not a denial. Ignore both its
+    // output and stderr; doctor is where hook health remains visible.
+    const successful = results.filter((result) => result.status === 0);
+    const messages = successful.map((result) => responseOf(result.stdout)).filter(Boolean);
+    if (["PreToolUse", "PermissionRequest"].includes(event)) {
+      const denied = messages.find((message) => message.hookSpecificOutput?.permissionDecision === "deny");
+      if (denied) return `${JSON.stringify(denied)}\n`;
+      const contexts = messages.map((message) => message.hookSpecificOutput?.additionalContext).filter(Boolean);
+      return contexts.length ? `${JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: contexts.join("\n") } })}\n` : "";
+    }
+    const structured = messages.map((message) => message.hookSpecificOutput?.additionalContext).filter(Boolean);
+    const plain = successful.map((result) => responseOf(result.stdout) ? "" : result.stdout.trim()).filter(Boolean);
+    if (["Stop", "SubagentStop"].includes(event)) return "{}\n";
+    return [...structured, ...plain].join("\n") + ([...structured, ...plain].length ? "\n" : "");
+  } catch {
+    return emptyResponse(event);
+  }
+}
+
+const versionParts = (value) => String(value ?? "").split(".").map((part) => Number.parseInt(part, 10));
+const atLeast = (actual, minimum) => {
+  const a = versionParts(actual);
+  const b = versionParts(minimum);
+  if (a.some(Number.isNaN) || b.some(Number.isNaN)) return false;
+  for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+    if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) > (b[i] ?? 0);
+  }
+  return true;
+};
+
+/** The managed dispatcher deliberately fails open; doctor makes that visible. */
+export async function managedHookCliStatus({ home = homedir(), read = readFile, accessImpl = access } = {}) {
+  let metadata;
+  try { metadata = JSON.parse(await read(join(managedHooksDir(home), "metadata.json"), "utf8")); }
+  catch (error) {
+    return { ok: false, reason: "metadata_missing", message: `managed hook metadata is unavailable (${error.code ?? error.message})` };
+  }
+  if (!isAbsolute(String(metadata.cliPath ?? ""))) return { ...metadata, ok: false, reason: "path_invalid", message: "managed hook nodii-dev path is not absolute" };
+  try { await accessImpl(metadata.cliPath, constants.X_OK); }
+  catch { return { ...metadata, ok: false, reason: "cli_missing", message: `managed hook CLI is missing or not executable: ${metadata.cliPath}` }; }
+  const minimum = metadata.minimumVersion ?? MANAGED_DISPATCH_MIN_VERSION;
+  if (!atLeast(metadata.cliVersion, minimum)) return { ...metadata, ok: false, reason: "cli_too_old", message: `managed hook CLI ${metadata.cliVersion ?? "unknown"} is older than ${minimum}` };
+  return { ...metadata, ok: true };
+}

package/dist/nodii-dev.js

@@ -1,4 +1,16 @@
 #!/usr/bin/env node
 import { fail, main } from "./cli.js";
 
-main().catch(fail);
+// Hooks run in the agent's environment, which may be incomplete or may not be
+// a git worktree. An unavailable hook must never turn into a refused tool call.
+// Intentional policy denials are handled inside the hook command before they
+// reach this boundary.
+main().catch((error) => {
+  const denial = String(error?.code ?? "").startsWith("SAFETY_") ||
+    ["FIGMA_FILE_KEY_MISSING", "FIGMA_LOCK_DENIED", "WRITE_OUT_OF_SCOPE"].includes(error?.code);
+  if (process.argv[2] === "hook" && !denial) {
+    process.exitCode = 0;
+    return;
+  }
+  fail(error);
+});

package/dist/safety.js

@@ -1,16 +1,18 @@
 import { execFile } from "node:child_process";
-import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
-import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { appendFile, mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import { CliError, configPath, devRequest, encode, readConfig } from "./core.js";
 
 const execFileAsync = promisify(execFile);
 const ACTIVE = new Set(["queued", "building", "built", "review", "on_main"]);
-const EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+const SHELL_TOOLS = new Set(["Bash", "shell", "exec_command"]);
+const EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit", "apply_patch"]);
 const GENERATED_MARK = /(?:do not edit|auto-?generated|generated (?:file|code)|@generated)/i;
 const REVIEW_RECEIPT = "nodii-review-receipt.json";
 const SAFETY_STATE = "nodii-safety-state.json";
 const SAFETY_AUDIT = "nodii-safety-audit.jsonl";
+export const HOOK_EVENTS = "nodii-hook-events.jsonl";
 
 async function optional(path) {
   try { return await readFile(path, "utf8"); }
@@ -25,6 +27,23 @@ async function gitPrivatePath(cwd, name) {
   return git(cwd, "rev-parse", "--path-format=absolute", "--git-path", name);
 }
 
+/** Minimal private receipt used by doctor to prove a runtime actually fired. */
+export async function recordHookFire(payload) {
+  const cwd = payload?.cwd ?? process.cwd();
+  const path = await gitPrivatePath(cwd, HOOK_EVENTS);
+  const event = {
+    at: new Date().toISOString(),
+    runtime: hookRuntime(payload),
+    event: payload?.hook_event_name ?? "unknown",
+    ...(payload?.source ? { source: payload.source } : {}),
+    ...(payload?.tool_name ? { tool: payload.tool_name } : {}),
+  };
+  if (event.runtime === "codex") event.profile = basename(process.env.CODEX_HOME ?? ".codex") === ".codex-work" ? "codex-work" : "codex-personal";
+  await mkdir(dirname(path), { recursive: true });
+  await appendFile(path, `${JSON.stringify(event)}\n`, { mode: 0o600 });
+  return event;
+}
+
 const cleanPath = (path) => String(path).split(sep).join("/").replace(/^\.\//, "");
 const quotePattern = (value) => value.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
 function globPattern(glob) {
@@ -121,12 +140,20 @@ function exactDeployGrant(context) {
   return context.deployGrants.some((x) => x === context.head);
 }
 
+const provenLane = (context) => context.provenLane === true || (context.provenLane === undefined && Boolean(context.lane));
+const nudgeViolation = (violation) => `nodii-dev safety: unproven lane context; ${violation.message.replace(/\bblocked\b/gi, "would be blocked")}`;
+
 /** Data-dependent checks nudge, rather than silently passing, when their source is not available yet. */
 export function commandNudges(command, context) {
   const tokens = words(command);
   const nudges = [];
   if (deployCommand(tokens, command) && !context.deployGrantKnown)
     nudges.push("nodii-dev safety: can't verify deploy authorization: no GO grant source is configured (follow-up AGENT-HARNESS-13).");
+  if (gitInvocations(tokens).some((x) => x.verb === "push")) {
+    if (!provenLane(context)) nudges.push("nodii-dev safety: can't verify review: this is not a proven current-lane context.");
+    else if (!context.reviewFlowKnown) nudges.push(`nodii-dev safety: can't verify review for ${context.lane?.key ?? context.branch}: Dev's lane review receipt flow is unavailable.`);
+  }
+  if (!provenLane(context)) nudges.push(...commandViolations(command, context).map(nudgeViolation));
   return nudges;
 }
 
@@ -135,10 +162,10 @@ export function commandViolations(command, context) {
   const tokens = words(command);
   const gitCommands = gitInvocations(tokens);
   const violations = [];
-  const lane = context.role !== "coordinator";
+  const lane = provenLane(context);
   const block = (code, message) => violations.push({ code, message });
 
-  if (gitCommands.some((x) => x.verb === "stash") && lane)
+  if (gitCommands.some((x) => x.verb === "stash"))
     block("SAFETY_GIT_STASH", "git stash is shared by every worktree; lanes and subagents use a work-in-progress commit.");
 
   for (const verb of ["checkout", "switch"]) {
@@ -168,7 +195,7 @@ export function commandViolations(command, context) {
     else if (!context.noVerifyReason) block("SAFETY_NO_VERIFY_REASON", "A coordinator may use --no-verify only with a recorded reason.");
   }
 
-  if (gitCommands.some((x) => x.verb === "push")) {
+  if (lane && context.reviewFlowKnown && gitCommands.some((x) => x.verb === "push")) {
     const receipt = context.reviewReceipt;
     if (!receipt) block("SAFETY_REVIEW_REQUIRED", `Push blocked: no review receipt for ${context.head}. Run nodii-dev lane review after the gates are green.`);
     else if (receipt.commit !== context.head)
@@ -177,7 +204,7 @@ export function commandViolations(command, context) {
       block("SAFETY_REVIEW_BASE", `Push blocked: review used base ${receipt.base}, but origin/main is ${context.base}. Re-review the current diff.`);
   }
 
-  if (lane && /(?:^|[\s/])(?:nodii-dev|@nodii\/dev(?:@[^\s]+)?)\s+(?:login|logout|agent\s+register)(?:\s|$)/.test(command))
+  if (/(?:^|[\s/])(?:nodii-dev|@nodii\/dev(?:@[^\s]+)?)\s+(?:login|logout|agent\s+register)(?:\s|$)/.test(command))
     block("SAFETY_IDENTITY", "A lane never runs nodii-dev login, logout or agent register; ask the coordinator.");
   if (/\bnodii\/prod(?:\/|\b)/i.test(command))
     block("SAFETY_PROD_SECRET", "nodii/prod secrets are outside lane authority.");
@@ -207,9 +234,11 @@ export function commandViolations(command, context) {
 /** Edit-tool ownership and generated-file blocks. */
 export async function editViolations(paths, context) {
   const violations = [];
+  const root = await realpath(context.root).catch(() => resolve(context.root));
   for (const path of paths) {
-    const absolute = isAbsolute(path) ? resolve(path) : resolve(context.cwd, path);
-    const rel = cleanPath(relative(context.root, absolute));
+    const unresolved = isAbsolute(path) ? resolve(path) : resolve(context.cwd, path);
+    const absolute = await realpath(unresolved).catch(async () => join(await realpath(dirname(unresolved)).catch(() => dirname(unresolved)), basename(unresolved)));
+    const rel = cleanPath(relative(root, absolute));
     if (rel === ".." || rel.startsWith("../") || isAbsolute(rel)) {
       violations.push({ code: "SAFETY_EDIT_OUTSIDE_REPO", message: `Edit blocked outside the lane repository: ${path}.` });
       continue;
@@ -224,8 +253,22 @@ export async function editViolations(paths, context) {
   return violations;
 }
 
+export function hookRuntime(payload) {
+  return payload?.model || payload?.turn_id || payload?.tool_name === "apply_patch" ? "codex" : "claude";
+}
+
+export function patchPaths(command) {
+  const paths = [];
+  for (const line of String(command ?? "").split(/\r?\n/)) {
+    const match = /^\*\*\* (?:Add|Update|Delete) File: (.+)$/.exec(line) ?? /^\*\*\* Move to: (.+)$/.exec(line);
+    if (match?.[1]?.trim()) paths.push(match[1].trim());
+  }
+  return [...new Set(paths)];
+}
+
 function editPaths(payload) {
   const input = payload.tool_input ?? {};
+  if (payload.tool_name === "apply_patch") return patchPaths(input.command);
   return [input.file_path, input.path, input.notebook_path, ...(Array.isArray(input.paths) ? input.paths : [])].filter((x) => typeof x === "string" && x);
 }
 
@@ -253,9 +296,15 @@ const laneStack = (key) => String(key ?? "").toLowerCase().replace(/[^a-z0-9_-]/
 async function currentLane(cwd, request, config) {
   if (!config?.agentId) return null;
   const branch = await git(cwd, "branch", "--show-current");
-  const root = await git(cwd, "rev-parse", "--show-toplevel");
+  const rootText = await git(cwd, "rev-parse", "--show-toplevel");
+  const root = await realpath(rootText).catch(() => resolve(rootText));
   const lanes = (await request("GET", "/api/v1/lanes?limit=200")).data ?? [];
-  return lanes.find((x) => x.agentId === config.agentId && x.branch === branch && resolve(x.worktree ?? root) === resolve(root) && ACTIVE.has(x.status)) ?? null;
+  for (const lane of lanes) {
+    if (lane.agentId !== config.agentId || lane.branch !== branch || !ACTIVE.has(lane.status)) continue;
+    const worktree = await realpath(lane.worktree ?? root).catch(() => resolve(lane.worktree ?? root));
+    if (worktree === root) return lane;
+  }
+  return null;
 }
 
 function deployGrantsFrom(text) {
@@ -264,7 +313,7 @@ function deployGrantsFrom(text) {
 
 /** Resolve the facts a hook needs without creating a second lane record. */
 export async function safetyContext(cwd = process.cwd(), { request = devRequest, configReader = readConfig, env = process.env } = {}) {
-  const root = await git(cwd, "rev-parse", "--show-toplevel");
+  const root = await realpath(await git(cwd, "rev-parse", "--show-toplevel"));
   const branch = await git(cwd, "branch", "--show-current");
   const head = await git(cwd, "rev-parse", "HEAD");
   const base = await git(cwd, "rev-parse", "origin/main");
@@ -277,6 +326,15 @@ export async function safetyContext(cwd = process.cwd(), { request = devRequest,
   }
   let lane = null;
   try { lane = await currentLane(cwd, request, config); } catch {}
+  let reviewFlowKnown = false;
+  if (lane) {
+    if (Array.isArray(lane.reviews)) reviewFlowKnown = true;
+    else try {
+      const detailed = (await request("GET", `/api/v1/lanes/${encode(lane.key)}`)).data;
+      reviewFlowKnown = Array.isArray(detailed?.reviews);
+      if (detailed && !Array.isArray(detailed)) lane = { ...lane, ...detailed };
+    } catch {}
+  }
   const receiptPath = await gitPrivatePath(cwd, REVIEW_RECEIPT);
   const statePath = await gitPrivatePath(cwd, SAFETY_STATE);
   const receiptText = await optional(receiptPath);
@@ -287,7 +345,7 @@ export async function safetyContext(cwd = process.cwd(), { request = devRequest,
   const ownership = laneOwnership(lane, root);
   const laneProject = laneStack(lane?.key);
   return {
-    cwd: payloadCwd(cwd), root, branch, head, base, role, lane,
+    cwd: await realpath(cwd).catch(() => payloadCwd(cwd)), root, branch, head, base, role, lane, provenLane: Boolean(lane), reviewFlowKnown,
     ownedPaths: ownership.paths,
     ownershipKnown: role === "coordinator" || ownership.known,
     generatedPaths: [...await harnessGenerated(root), ...(state.generatedPaths ?? [])],
@@ -306,30 +364,37 @@ function blocked(violation) {
   throw new CliError(violation.code, violation.message, 2);
 }
 
-/** Claude PreToolUse entrypoint. Silent return means allowed. */
+/** Runtime-neutral PreToolUse entrypoint. Silent return means allowed. */
 export async function safetyPreHook(payload, contextOrResolver = safetyContext) {
   const tool = payload.tool_name ?? "";
-  if (tool !== "Bash" && !EDIT_TOOLS.has(tool)) return { allowed: true, ignored: true };
+  if (!SHELL_TOOLS.has(tool) && !EDIT_TOOLS.has(tool)) return { allowed: true, ignored: true };
   const cwd = payload.cwd ?? process.cwd();
   const context = typeof contextOrResolver === "function" ? await contextOrResolver(cwd) : contextOrResolver;
-  context.cwd = resolve(cwd);
-  if (tool === "Bash") {
+  context.cwd = await realpath(cwd).catch(() => resolve(cwd));
+  if (SHELL_TOOLS.has(tool)) {
     const command = String(payload.tool_input?.command ?? "");
     const violation = commandViolations(command, context)[0];
-    if (violation) blocked(violation);
+    if (violation && provenLane(context)) blocked(violation);
     if (usesNoVerify(command) && context.role === "coordinator" && context.noVerifyReason)
       await recordNoVerifyReason(cwd, context.noVerifyReason);
     return { allowed: true, nudges: commandNudges(command, context) };
   }
   const paths = editPaths(payload);
-  if (!paths.length) blocked({ code: "SAFETY_EDIT_PATH_MISSING", message: `Edit blocked: ${tool} supplied no file path.` });
+  if (!paths.length) {
+    const violation = { code: "SAFETY_EDIT_PATH_MISSING", message: `Edit blocked: ${tool} supplied no file path.` };
+    if (provenLane(context)) blocked(violation);
+    return { allowed: true, nudges: [nudgeViolation(violation)] };
+  }
   const violation = (await editViolations(paths, context))[0];
-  if (violation) blocked(violation);
+  if (violation && provenLane(context)) blocked(violation);
   return {
     allowed: true,
-    nudges: context.role !== "coordinator" && !context.ownershipKnown
-      ? ["nodii-dev safety: can't verify owned paths: the lane has no Dev ownedPaths field yet (follow-up AGENT-HARNESS-10)."]
-      : [],
+    nudges: [
+      ...(!provenLane(context) && violation ? [nudgeViolation(violation)] : []),
+      ...(context.role !== "coordinator" && !context.ownershipKnown
+        ? ["nodii-dev safety: can't verify owned paths: the lane has no Dev ownedPaths field yet (follow-up AGENT-HARNESS-10)."]
+        : []),
+    ],
   };
 }
 
@@ -351,7 +416,7 @@ function successful(payload) {
 
 /** Record only successful resource creation; says nothing when satisfied. */
 export async function safetyPostHook(payload) {
-  if (payload.tool_name !== "Bash" || !successful(payload)) return { recorded: false };
+  if (!SHELL_TOOLS.has(payload.tool_name) || !successful(payload)) return { recorded: false };
   const command = String(payload.tool_input?.command ?? "");
   const tokens = words(command);
   const cwd = payload.cwd ?? process.cwd();
@@ -402,3 +467,16 @@ export const safetySettingsSnippet = () => ({
     PostToolUse: [{ matcher: "^Bash$", hooks: [{ type: "command", command: "nodii-dev hook safety-post" }] }],
   },
 });
+
+export const codexSafetyHooksSnippet = () => ({
+  hooks: {
+    PreToolUse: [{ matcher: "^(Bash|apply_patch)$", hooks: [{ type: "command", command: "nodii-dev hook safety-pre" }] }],
+    PostToolUse: [{ matcher: "^Bash$", hooks: [{ type: "command", command: "nodii-dev hook safety-post" }] }],
+  },
+});
+
+export const regroundingHooksSnippet = () => ({
+  hooks: {
+    SessionStart: [{ matcher: "^compact$", hooks: [{ type: "command", command: "nodii-dev hook session-start" }] }],
+  },
+});

package/dist/setup.js

@@ -1,7 +1,8 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { CliError, checkLogin } from "./core.js";
-import { safetySettingsSnippet } from "./safety.js";
+import { codexHooksFromClaude } from "./harness.js";
+import { regroundingHooksSnippet, safetySettingsSnippet } from "./safety.js";
 
 export const SKILL_PATH = ".claude/skills/nodii-build-workflow/SKILL.md";
 const START = "<!-- nodii-dev build workflow:start -->";
@@ -47,7 +48,10 @@ ${END}`;
 export const workflowHooks = () => {
   const safety = safetySettingsSnippet().hooks;
   return {
-    SessionStart: [{ hooks: [{ type: "command", command: "nodii-dev lane list --mine --json" }] }],
+    SessionStart: [
+      { hooks: [{ type: "command", command: "nodii-dev lane list --mine --json" }] },
+      ...regroundingHooksSnippet().hooks.SessionStart,
+    ],
     Stop: [{ hooks: [{ type: "command", command: "nodii-dev hook lane-heartbeat" }] }],
     PreToolUse: safety.PreToolUse,
     PostToolUse: [
@@ -70,6 +74,12 @@ export function mergeSettings(current = {}) {
   return { ...current, hooks };
 }
 
+export function mergeCodexHooks(current = {}) {
+  const hooks = { ...(current.hooks ?? {}) };
+  for (const [event, entries] of Object.entries(codexHooksFromClaude(workflowHooks()))) hooks[event] = mergeHookList(hooks[event], entries);
+  return { ...current, hooks };
+}
+
 export function updateMarkedDocument(text = "") {
   const block = new RegExp(`${START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`);
   if (block.test(text)) return `${text.replace(block, managedBlock).trimEnd()}\n`;
@@ -86,12 +96,18 @@ export async function setupPlan(root = process.cwd()) {
   let parsed = {};
   try { parsed = existingSettings ? JSON.parse(existingSettings) : {}; }
   catch { throw new CliError("INVALID_SETTINGS", `${settingsPath} is not valid JSON; fix it before setup.`, 2); }
+  const codexHooksPath = join(root, ".codex/hooks.json");
+  const existingCodexHooks = await optional(codexHooksPath);
+  let parsedCodexHooks = {};
+  try { parsedCodexHooks = existingCodexHooks ? JSON.parse(existingCodexHooks) : {}; }
+  catch { throw new CliError("INVALID_SETTINGS", `${codexHooksPath} is not valid JSON; fix it before setup.`, 2); }
   const claude = join(root, "CLAUDE.md");
   const agents = join(root, "AGENTS.md");
   const documentPath = (await optional(claude)) !== null ? claude : (await optional(agents)) !== null ? agents : claude;
   const desired = new Map([
     [join(root, SKILL_PATH), workflowSkill],
     [settingsPath, `${JSON.stringify(mergeSettings(parsed), null, 2)}\n`],
+    [codexHooksPath, `${JSON.stringify(mergeCodexHooks(parsedCodexHooks), null, 2)}\n`],
     [documentPath, updateMarkedDocument((await optional(documentPath)) ?? "")],
   ]);
   const changes = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodii/dev",
-  "version": "0.6.25",
+  "version": "0.6.27",
   "description": "Agent CLI for Nodii Dev, reached through the platform edge",
   "type": "module",
   "bin": {