hilos-agent 0.9.1 → 0.9.2

package/src/hook.mjs

@@ -11,20 +11,24 @@
 //     step ring and last-send time, so most invocations are one small read +
 //     at most one bounded fetch. Sends are throttled (default 2s) with pending
 //     steps carried over — a burst of tool calls becomes one coalesced update.
-//   - Privacy is the install default: `hooks install` writes project-local
-//     Codex, Claude, and Cursor hook files, so only repos you opt in ever stream.
+//   - Privacy is the install default: Claude/Cursor use project-local hook files.
+//     Codex needs one global hook because `codex exec` skips repository hooks;
+//     hilos enforces the same project-local consent with a 0600 path allowlist.
 //     HILOS_HOOKS=off is the global kill switch.
 //   - Pure helpers (event parsing, step labels, throttling decisions) are
 //     exported for offline unit tests; I/O lives only in runHook/main.
 
-import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, unlinkSync, existsSync, chmodSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, unlinkSync, existsSync, chmodSync, realpathSync, cpSync, renameSync, rmSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
-import { join, dirname, delimiter } from "node:path";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { sanitizeText, webTarget } from "./agent-events.mjs";
 import { resolveConfig } from "./config.mjs";
 
 export const HOOK_STATE_DIR = join(homedir(), ".hilos", "hook-state");
+export const CODEX_HOOK_SCOPE_FILE = join(homedir(), ".hilos", "codex-hook-scope.json");
+export const HOOK_RUNTIME_ROOT = join(homedir(), ".hilos", "hook-runtime");
 /** Coalesce window between sends; Stop/SessionEnd always flush. */
 const MIN_SEND_MS = 2000;
 /** A hook must never hang the CLI on a slow network. */
@@ -35,6 +39,122 @@ const MAX_FILES = 20;
 /** Session state older than this is dead — GC'd opportunistically. */
 const STATE_TTL_MS = 48 * 60 * 60 * 1000;
 
+function normalizedProjectPath(value) {
+  if (typeof value !== "string" || !value.trim()) return "";
+  try {
+    return realpathSync(value.trim());
+  } catch {
+    return value.trim();
+  }
+}
+
+/**
+ * Resolve a working directory to the nearest repository/worktree root. Codex
+ * reports the directory it was launched from, which is often below the root
+ * where `hooks install` ran. Choosing the nearest `.git` boundary also keeps an
+ * opted-in parent repository from implicitly opting in a nested repository.
+ * Non-git folders remain exact-path opt-ins.
+ */
+function codexProjectPath(value) {
+  const project = normalizedProjectPath(value);
+  if (!project) return "";
+  let current = project;
+  while (true) {
+    if (existsSync(join(current, ".git"))) return current;
+    const parent = dirname(current);
+    if (parent === current) return project;
+    current = parent;
+  }
+}
+
+function validCodexHookScope(scope) {
+  return Boolean(
+    scope &&
+    typeof scope === "object" &&
+    scope.version === 1 &&
+    typeof scope.global === "boolean" &&
+    Array.isArray(scope.projects) &&
+    scope.projects.every((project) => typeof project === "string" && project.trim()),
+  );
+}
+
+/**
+ * Codex CLI 0.144 runs global hooks for both the interactive TUI and
+ * `codex exec`, but repository hooks only for the interactive lane. Keep one
+ * global command so both workflows work, then enforce project-local consent in
+ * our own small allowlist. `global:true` is the explicit --global opt-in.
+ */
+export function codexHookScopeAllows(scope, cwd) {
+  if (!scope || typeof scope !== "object") return false;
+  if (scope.global === true) return true;
+  const project = codexProjectPath(cwd);
+  return Boolean(project) && (Array.isArray(scope.projects) ? scope.projects : [])
+    .map(codexProjectPath)
+    .includes(project);
+}
+
+/** Decide whether a Codex event may reach hilos. A present-but-malformed scope
+ * file is an explicit deny: corruption must never widen reporting to every
+ * repository. With no scope file, only an old unmarked command can preserve
+ * pre-0854 consent. New commands identify themselves as
+ * scope-managed and deny when their private state is lost.
+ * @param {{
+ *   scopeFileExists?: boolean,
+ *   scope?: {version?: unknown, global?: unknown, projects?: unknown} | null,
+ *   cwd?: string,
+ *   legacyUnscopedHook?: boolean,
+ * }} [options]
+ */
+export function codexHookMayRun({
+  scopeFileExists = false,
+  scope = null,
+  cwd = "",
+  legacyUnscopedHook = false,
+} = {}) {
+  if (!scopeFileExists) return legacyUnscopedHook === true;
+  if (!validCodexHookScope(scope)) return false;
+  const managedAllows = codexHookScopeAllows(scope, cwd);
+  // A managed home hook owns paths already in the allowlist. An old unmarked
+  // project hook owns only a path the new allowlist does not yet know about.
+  // Thus two pre-0.9.2 repo opt-ins keep working while A never double-fires
+  // after installing 0.9.2 and B can be migrated independently later.
+  return legacyUnscopedHook === true ? !managedAllows : managedAllows;
+}
+
+export function readCodexHookScope(path = CODEX_HOOK_SCOPE_FILE) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeCodexHookScope({ cwd = "", global = false } = {}, path = CODEX_HOOK_SCOPE_FILE) {
+  try {
+    const prior = readCodexHookScope(path) || {};
+    const projects = new Set(
+      (Array.isArray(prior.projects) ? prior.projects : [])
+        .map(codexProjectPath)
+        .filter(Boolean),
+    );
+    const project = codexProjectPath(cwd);
+    if (project) projects.add(project);
+    const next = {
+      version: 1,
+      global: prior.global === true || global === true,
+      projects: [...projects].sort(),
+    };
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    chmodSync(dirname(path), 0o700);
+    writeFileSync(path, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+    chmodSync(path, 0o600);
+    return next;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Scope local hook state to one hilos agent credential without ever writing the
  * bearer token itself to disk. Two agent identities can share a machine, so a
@@ -159,12 +279,27 @@ export function mcpResponsePayload(value, depth = 0) {
 export function bindingFromHookEvent(ev, at = new Date().toISOString()) {
   if (!ev || ev.event !== "PostToolUse") return null;
   const match = String(ev.toolName || "").match(/^mcp__(.+?)__(post_message|post_report)$/i);
-  if (!match || !/hilos/i.test(match[1])) return null;
+  if (!match) return null;
   const channelId = typeof ev.toolInput?.channelId === "string" ? ev.toolInput.channelId : "";
   if (!channelId) return null;
   const payload = mcpResponsePayload(ev.toolResponse);
   const messageId = typeof payload?.messageId === "string" ? payload.messageId : "";
   const agentId = typeof payload?.agentId === "string" ? payload.agentId : "";
+  const bindingClaim = typeof payload?.bindingClaim === "string" ? payload.bindingClaim : "";
+  const serverName = match[1].toLowerCase();
+  // Codex config preserves `hilos-<compact uuid>`, but its PostToolUse event
+  // normalizes that hyphen to an underscore. Both spellings refer to the same
+  // configured server; the UUID still has to equal the authenticated result.
+  const canonical = /^hilos[-_]([0-9a-f]{32})$/.exec(serverName);
+  // The in-app Codex setup uses an immutable UUID-derived server name. Accept
+  // that (including Codex's event normalization) only when it names the
+  // authenticated result's agent exactly; retain
+  // the documented generic `hilos` name for Claude/Cursor/manual setups. A
+  // coincidental `hilos_fake` server is never a binding source.
+  if (
+    serverName !== "hilos" &&
+    (!canonical || agentId.replaceAll("-", "").toLowerCase() !== canonical[1])
+  ) return null;
   // The server-authenticated author is part of the result. Requiring it keeps a
   // differently configured hilos MCP connection from being resumed and posted
   // through this daemon's identity merely because both can access the room.
@@ -175,6 +310,7 @@ export function bindingFromHookEvent(ev, at = new Date().toISOString()) {
     anchorMessageId: messageId,
     channelId,
     agentId,
+    ...(bindingClaim ? { bindingClaim } : {}),
     boundAt: at,
     processedReplyIds: [],
   };
@@ -207,7 +343,13 @@ function sessionState(state, ev, vendor, now, token) {
   out.sessionId = ev.sessionId;
   out.vendor = vendor || out.vendor || "unknown";
   out.cwd = ev.cwd || out.cwd || "";
-  out.connectionKey = hookConnectionKey(token);
+  // The zero-config `--join` path deliberately keeps its bearer token only in
+  // the daemon process. Lifecycle hooks are separate child processes, so they
+  // cannot fingerprint that credential. Preserve a prior fingerprint when one
+  // exists; otherwise the server-authenticated agent id on each MCP binding is
+  // the daemon's claim key (reply-bridge.mjs).
+  if (token) out.connectionKey = hookConnectionKey(token);
+  else if (typeof out.connectionKey !== "string") out.connectionKey = "";
   out.updatedAt = new Date(now()).toISOString();
   if (!Array.isArray(out.bindings)) out.bindings = [];
   return out;
@@ -358,10 +500,13 @@ export function deleteState(sessionId, dir = HOOK_STATE_DIR) {
   }
 }
 
-/** Drop state files from long-dead sessions. Best-effort, bounded, silent. */
+/** Drop state files from long-dead sessions. Best-effort and silent. */
 export function gcStateDir(dir = HOOK_STATE_DIR, now = Date.now()) {
   try {
-    for (const f of readdirSync(dir).slice(0, 200)) {
+    // readdir order is arbitrary, so slicing can leave the same expired tail
+    // forever. SessionStart is infrequent enough to inspect this private,
+    // metadata-only directory completely and keep zero-config use bounded.
+    for (const f of readdirSync(dir).filter((name) => name.endsWith(".json"))) {
       const p = join(dir, f);
       try {
         if (now - statSync(p).mtimeMs > STATE_TTL_MS) unlinkSync(p);
@@ -419,9 +564,13 @@ export async function runHook({ raw, cfg, vendor = "unknown", now = Date.now, st
   const ev = parseHookEvent(raw);
   if (!ev) return;
   const { url, token, channelId } = cfg;
-  if (!url || !token) return; // not connected to hilos — no-op
 
-  let state = sessionState(readState(ev.sessionId, stateDir), ev, vendor, now, token);
+  const priorState = readState(ev.sessionId, stateDir);
+  // Providers normally send SessionStart, but cleanup must not depend on that
+  // lifecycle guarantee. The first event for any new session is a bounded-cost
+  // opportunity to sweep old zero-config files too.
+  if (!priorState) gcStateDir(stateDir, now());
+  let state = sessionState(priorState, ev, vendor, now, token);
   const binding = bindingFromHookEvent(ev, new Date(now()).toISOString());
   if (binding) upsertBinding(state, binding);
 
@@ -442,7 +591,7 @@ export async function runHook({ raw, cfg, vendor = "unknown", now = Date.now, st
     // anything right now". The next tool call revives the SAME card to working
     // via its stored messageId, so a session stays one card, not one per turn.
     state.active = false;
-    if (state.messageId) {
+    if (url && token && state.messageId) {
       await sendProgress({
         url,
         token,
@@ -473,10 +622,15 @@ export async function runHook({ raw, cfg, vendor = "unknown", now = Date.now, st
     return;
   }
 
-  if (!state.startedAt) {
-    gcStateDir(stateDir, now()); // new session — a cheap moment to sweep old ones
-    state.startedAt = now();
+  // A raw session can still bind its successful Hilos MCP posts when the
+  // daemon was launched with memory-only `--join` credentials. There is no
+  // credential here for ambient progress, so keep only local lifecycle state.
+  if (!url || !token) {
+    writeState(ev.sessionId, state, stateDir);
+    return;
   }
+
+  if (!state.startedAt) state.startedAt = now();
   foldStep(state, step);
 
   // A config without a default channel can still bind explicit hilos MCP posts
@@ -541,10 +695,24 @@ function readStdin() {
 }
 
 /** `hilos-agent hook` — the command each provider invokes. Always exits 0. */
-export async function hookMain({ vendor = "unknown" } = {}) {
+export async function hookMain({ vendor = "unknown", scopeManaged = false } = {}) {
   try {
     if (/^(off|0|false)$/i.test(process.env.HILOS_HOOKS || "")) return;
     const raw = await readStdin();
+    if (vendor === "codex") {
+      const event = parseHookEvent(raw);
+      if (!event) return;
+      const scope = readCodexHookScope();
+      if (!codexHookMayRun({
+        scopeFileExists: existsSync(CODEX_HOOK_SCOPE_FILE),
+        scope,
+        cwd: event.cwd,
+        // 0.9.1 and older wrote an unmarked command. A home-level instance was
+        // only created by explicit `--global`, so retain that consent. New
+        // installs carry --scope-managed and fail closed if their scope is lost.
+        legacyUnscopedHook: scopeManaged !== true,
+      })) return;
+    }
     const cfg = resolveConfig({});
     await runHook({ raw, cfg, vendor });
   } catch {
@@ -555,12 +723,89 @@ export async function hookMain({ vendor = "unknown" } = {}) {
 // --- `hilos-agent hooks print|install [--global]` ---------------------------
 
 const CLAUDE_HOOK_COMMAND = "hilos-agent hook --vendor claude_code";
-const CODEX_HOOK_COMMAND = "hilos-agent hook --vendor codex";
+const LEGACY_CODEX_HOOK_COMMAND = "hilos-agent hook --vendor codex";
+const CODEX_HOOK_COMMAND = "hilos-agent hook --vendor codex --scope-managed";
 const CURSOR_HOOK_COMMAND = "hilos-agent hook --vendor cursor";
 
+function hookCommandArg(value, platform = process.platform) {
+  const text = String(value);
+  if (/^[a-zA-Z0-9_./:\\-]+$/.test(text)) return text;
+  if (platform === "win32") {
+    // Hook commands are interpreted by the provider's Windows command runner.
+    // Double quotes preserve spaces; doubled quotes and percent signs remain
+    // literal instead of becoming command syntax/environment expansion.
+    return `"${text.replaceAll("%", "%%").replaceAll('"', '""')}"`;
+  }
+  return `'${text.replaceAll("'", `'"'"'`)}'`;
+}
+
+/**
+ * Install a dependency-free, versioned copy of the hook entrypoint. `npx`
+ * exposes its temporary .bin directory only for the installer process, so a
+ * later Codex/Claude/Cursor hook cannot safely rely on `hilos-agent` being on
+ * PATH. The private runtime makes the documented npx flow durable and offline.
+ */
+export function installHookRuntime({
+  sourceRoot = dirname(dirname(fileURLToPath(import.meta.url))),
+  runtimeRoot = HOOK_RUNTIME_ROOT,
+  nodePath = process.execPath,
+} = {}) {
+  try {
+    const manifest = JSON.parse(readFileSync(join(sourceRoot, "package.json"), "utf8"));
+    const version = typeof manifest?.version === "string" && /^[0-9A-Za-z.+-]+$/.test(manifest.version)
+      ? manifest.version
+      : "unknown";
+    mkdirSync(runtimeRoot, { recursive: true, mode: 0o700 });
+    chmodSync(runtimeRoot, 0o700);
+    const target = join(runtimeRoot, version);
+    const entry = join(target, "bin", "hilos-agent.mjs");
+    if (!existsSync(entry)) {
+      const temporary = join(runtimeRoot, `.install-${process.pid}-${Date.now()}`);
+      try {
+        mkdirSync(temporary, { recursive: true, mode: 0o700 });
+        cpSync(join(sourceRoot, "bin"), join(temporary, "bin"), { recursive: true });
+        cpSync(join(sourceRoot, "src"), join(temporary, "src"), { recursive: true });
+        cpSync(join(sourceRoot, "package.json"), join(temporary, "package.json"));
+        try {
+          renameSync(temporary, target);
+        } catch (error) {
+          // A simultaneous installer may have won the atomic rename. Its fully
+          // written entry is equivalent; any other failure remains fatal.
+          if (!existsSync(entry)) throw error;
+        }
+      } finally {
+        if (existsSync(temporary)) rmSync(temporary, { recursive: true, force: true });
+      }
+    }
+    if (!existsSync(entry)) return null;
+    return `${hookCommandArg(nodePath)} ${hookCommandArg(entry)}`;
+  } catch {
+    return null;
+  }
+}
+
+function managedHookCommand(command, vendor) {
+  return typeof command === "string" &&
+    command.includes(" hook --managed-runtime ") &&
+    command.includes(`--vendor ${vendor}`);
+}
+
+function hookCommands(commandBase = "hilos-agent") {
+  return {
+    claude: `${commandBase} hook --managed-runtime --vendor claude_code`,
+    codex: `${commandBase} hook --managed-runtime --vendor codex --scope-managed`,
+    cursor: `${commandBase} hook --managed-runtime --vendor cursor`,
+  };
+}
+
+function codexHome() {
+  const configured = typeof process.env.CODEX_HOME === "string" ? process.env.CODEX_HOME.trim() : "";
+  return configured || join(homedir(), ".codex");
+}
+
 /** The hooks block hilos needs inside a Claude Code settings.json. */
-export function hilosHooksBlock() {
-  const entry = { hooks: [{ type: "command", command: CLAUDE_HOOK_COMMAND }] };
+export function hilosHooksBlock(command = CLAUDE_HOOK_COMMAND) {
+  const entry = { hooks: [{ type: "command", command }] };
   return {
     SessionStart: [{ matcher: "startup|resume|clear|compact", ...entry }],
     UserPromptSubmit: [entry],
@@ -571,9 +816,9 @@ export function hilosHooksBlock() {
 }
 
 /** The equivalent project/global hooks file Codex discovers in `.codex/`. */
-export function hilosCodexHooksBlock() {
-  const entry = { hooks: [{ type: "command", command: CODEX_HOOK_COMMAND, timeout: 5 }] };
-  const sessionEnd = { hooks: [{ type: "command", command: CODEX_HOOK_COMMAND, timeout: 3 }] };
+export function hilosCodexHooksBlock(command = CODEX_HOOK_COMMAND) {
+  const entry = { hooks: [{ type: "command", command, timeout: 5 }] };
+  const sessionEnd = { hooks: [{ type: "command", command, timeout: 3 }] };
   return {
     SessionStart: [{ matcher: "startup|resume|clear|compact", ...entry }],
     UserPromptSubmit: [entry],
@@ -584,8 +829,8 @@ export function hilosCodexHooksBlock() {
 }
 
 /** Cursor's native hooks.json uses lower-camel event names and flat commands. */
-export function hilosCursorHooksBlock() {
-  const entry = { command: CURSOR_HOOK_COMMAND, timeout: 5 };
+export function hilosCursorHooksBlock(command = CURSOR_HOOK_COMMAND) {
+  const entry = { command, timeout: 5 };
   return {
     sessionStart: [entry],
     beforeSubmitPrompt: [entry],
@@ -598,7 +843,7 @@ export function hilosCursorHooksBlock() {
   };
 }
 
-function mergeHookBlock(settings, block, command) {
+function mergeHookBlock(settings, block, command, { vendor = "", legacy = [] } = {}) {
   const out = settings && typeof settings === "object" ? settings : {};
   const hooks = (out.hooks = out.hooks && typeof out.hooks === "object" ? out.hooks : {});
   let changed = false;
@@ -608,9 +853,14 @@ function mergeHookBlock(settings, block, command) {
     for (const group of existing) {
       for (const handler of group?.hooks || []) {
         if (handler?.command === command) found = true;
-        // Upgrade the pre-0847 Claude-only command in place. Copy-on-write is
-        // not useful here: the old helper already mutates the passed settings.
-        if (command === CLAUDE_HOOK_COMMAND && handler?.command === "hilos-agent hook") {
+        // Upgrade an earlier package command (including a versioned private
+        // runtime) in place while preserving the user's grouping/matcher.
+        if (
+          handler?.command !== command && (
+            legacy.includes(handler?.command) ||
+            (vendor && managedHookCommand(handler?.command, vendor))
+          )
+        ) {
           handler.command = command;
           found = true;
           changed = true;
@@ -630,22 +880,72 @@ function mergeHookBlock(settings, block, command) {
  * settings.json). Existing user hooks are preserved; a second install is a
  * no-op. PURE — returns { settings, changed }.
  */
-export function mergeHooksIntoSettings(settings) {
-  return mergeHookBlock(settings, hilosHooksBlock(), CLAUDE_HOOK_COMMAND);
+export function mergeHooksIntoSettings(settings, command = CLAUDE_HOOK_COMMAND) {
+  return mergeHookBlock(settings, hilosHooksBlock(command), command, {
+    vendor: "claude_code",
+    legacy: ["hilos-agent hook", CLAUDE_HOOK_COMMAND],
+  });
 }
 
-export function mergeCodexHooksIntoSettings(settings) {
-  return mergeHookBlock(settings, hilosCodexHooksBlock(), CODEX_HOOK_COMMAND);
+export function mergeCodexHooksIntoSettings(settings, command = CODEX_HOOK_COMMAND) {
+  // Upgrade the old unscoped command in place. Its old location still tells
+  // hookMain whether it was project-local or explicit-global until install is
+  // rerun, while every newly written command is scope-managed.
+  const migrated = removeCodexHooksFromSettings(
+    settings,
+    [LEGACY_CODEX_HOOK_COMMAND, CODEX_HOOK_COMMAND],
+    command,
+  );
+  const merged = mergeHookBlock(migrated.settings, hilosCodexHooksBlock(command), command, {
+    vendor: "codex",
+  });
+  return { settings: merged.settings, changed: migrated.changed || merged.changed };
+}
+
+/** Remove only hilos's Codex handlers, preserving every user handler/group. */
+export function removeCodexHooksFromSettings(
+  settings,
+  commands = [CODEX_HOOK_COMMAND, LEGACY_CODEX_HOOK_COMMAND],
+  keepCommand = "",
+) {
+  const out = settings && typeof settings === "object" ? settings : {};
+  const hooks = out.hooks && typeof out.hooks === "object" ? out.hooks : {};
+  let changed = false;
+  for (const [event, groups] of Object.entries(hooks)) {
+    if (!Array.isArray(groups)) continue;
+    const nextGroups = [];
+    for (const group of groups) {
+      const handlers = Array.isArray(group?.hooks) ? group.hooks : [];
+      const kept = handlers.filter((handler) =>
+        handler?.command === keepCommand || (
+          !commands.includes(handler?.command) && !managedHookCommand(handler?.command, "codex")
+        ));
+      if (kept.length !== handlers.length) changed = true;
+      if (kept.length) nextGroups.push({ ...group, hooks: kept });
+      else if (!handlers.length) nextGroups.push(group);
+    }
+    if (nextGroups.length) hooks[event] = nextGroups;
+    else if (groups.length) delete hooks[event];
+  }
+  out.hooks = hooks;
+  return { settings: out, changed };
 }
 
-export function mergeCursorHooksIntoSettings(settings) {
+export function mergeCursorHooksIntoSettings(settings, command = CURSOR_HOOK_COMMAND) {
   const out = settings && typeof settings === "object" ? settings : {};
   let changed = out.version !== 1;
   if (changed) out.version = 1;
   const hooks = (out.hooks = out.hooks && typeof out.hooks === "object" ? out.hooks : {});
-  for (const [event, entries] of Object.entries(hilosCursorHooksBlock())) {
+  for (const [event, entries] of Object.entries(hilosCursorHooksBlock(command))) {
     const existing = Array.isArray(hooks[event]) ? hooks[event] : [];
-    if (!existing.some((handler) => handler?.command === CURSOR_HOOK_COMMAND)) {
+    const prior = existing.find((handler) =>
+      handler?.command === CURSOR_HOOK_COMMAND || managedHookCommand(handler?.command, "cursor"));
+    if (prior) {
+      if (prior.command !== command) {
+        prior.command = command;
+        changed = true;
+      }
+    } else {
       hooks[event] = [...existing, ...entries];
       changed = true;
     }
@@ -654,7 +954,7 @@ export function mergeCursorHooksIntoSettings(settings) {
 }
 
 /** `hilos-agent hooks install [--global]` / `hilos-agent hooks print`. */
-function installHooksFile({ target, merge, label, scope }) {
+export function installHooksFile({ target, merge, label, scope }) {
   let current = {};
   if (existsSync(target)) {
     try {
@@ -670,14 +970,40 @@ function installHooksFile({ target, merge, label, scope }) {
     console.log(`${label} hilos hooks already installed in ${target}.`);
     return true;
   }
-  if (existsSync(target)) writeFileSync(target + ".bak", readFileSync(target));
-  mkdirSync(dirname(target), { recursive: true });
-  writeFileSync(target, JSON.stringify(settings, null, 2) + "\n");
+  try {
+    if (existsSync(target)) writeFileSync(target + ".bak", readFileSync(target));
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, JSON.stringify(settings, null, 2) + "\n");
+  } catch {
+    // Callers use the boolean to roll back any authority state they changed
+    // before this write (Codex's repo allowlist). Filesystem failures are an
+    // install refusal, never an uncaught half-install.
+    console.error(`Could not write ${target}; no hook was installed. Check the file permissions and try again.`);
+    process.exitCode = 1;
+    return false;
+  }
   console.log(`Installed ${label} hilos hooks into ${target}${existsSync(target + ".bak") ? ` (backup: ${target}.bak)` : ""}.`);
   console.log(`${scope} ${label} sessions can now stream to hilos and bind replies to the same local session.`);
   return true;
 }
 
+function removeProjectCodexHook(target) {
+  if (!existsSync(target)) return false;
+  try {
+    const current = JSON.parse(readFileSync(target, "utf8"));
+    const { settings, changed } = removeCodexHooksFromSettings(current);
+    if (!changed) return false;
+    writeFileSync(target + ".bak", readFileSync(target));
+    writeFileSync(target, JSON.stringify(settings, null, 2) + "\n");
+    console.log(`Moved the hilos Codex hook out of ${target}; other project hooks were preserved (backup: ${target}.bak).`);
+    return true;
+  } catch {
+    // installHooksFile reports malformed global files; a malformed legacy
+    // project file is left untouched rather than risk deleting user config.
+    return false;
+  }
+}
+
 export function hooksMain(sub, { global: isGlobal = false, client = "all" } = {}) {
   if (sub === "print") {
     if (client !== "codex" && client !== "cursor") {
@@ -685,7 +1011,7 @@ export function hooksMain(sub, { global: isGlobal = false, client = "all" } = {}
       console.log(JSON.stringify({ hooks: hilosHooksBlock() }, null, 2));
     }
     if (client !== "claude" && client !== "cursor") {
-      console.log("\nCodex (.codex/hooks.json):");
+      console.log("\nCodex (~/.codex/hooks.json, project access allowlisted by hilos-agent):");
       console.log(JSON.stringify({ description: "hilos local session bridge", hooks: hilosCodexHooksBlock() }, null, 2));
     }
     if (client !== "claude" && client !== "codex") {
@@ -698,47 +1024,89 @@ export function hooksMain(sub, { global: isGlobal = false, client = "all" } = {}
     console.log("Usage: hilos-agent hooks <install|print> [--global] [--claude|--codex|--cursor]");
     return;
   }
-  const scope = isGlobal ? "Every opted-in" : "This repo's";
+  const runtime = installHookRuntime();
+  if (!runtime) {
+    console.error("Could not install the private hilos hook runtime. Check ~/.hilos permissions and try again; no hook was changed.");
+    process.exitCode = 1;
+    return;
+  }
+  const commands = hookCommands(runtime);
+  const scope = isGlobal ? "Every" : "This repo's";
   if (client !== "codex" && client !== "cursor") {
     installHooksFile({
       target: isGlobal
         ? join(homedir(), ".claude", "settings.json")
         : join(process.cwd(), ".claude", "settings.json"),
-      merge: mergeHooksIntoSettings,
+      merge: (settings) => mergeHooksIntoSettings(settings, commands.claude),
       label: "Claude Code",
       scope,
     });
   }
   if (client !== "claude" && client !== "cursor") {
-    installHooksFile({
-      target: isGlobal
-        ? join(homedir(), ".codex", "hooks.json")
-        : join(process.cwd(), ".codex", "hooks.json"),
-      merge: mergeCodexHooksIntoSettings,
-      label: "Codex",
-      scope,
-    });
-    console.log("Codex asks you to review new project hooks once; open /hooks and trust the hilos entries.");
+    const globalTarget = join(codexHome(), "hooks.json");
+    const scopeExisted = existsSync(CODEX_HOOK_SCOPE_FILE);
+    let priorScope = null;
+    try {
+      if (scopeExisted) priorScope = readFileSync(CODEX_HOOK_SCOPE_FILE);
+    } catch {
+      // A scope we cannot back up also cannot be safely replaced.
+      priorScope = null;
+    }
+    // Record consent before installing a home-level executable hook. If the
+    // private scope file cannot be written, nothing new is allowed to run.
+    const recorded = scopeExisted && !priorScope
+      ? null
+      : writeCodexHookScope({ cwd: isGlobal ? "" : process.cwd(), global: isGlobal });
+    if (!recorded) {
+      console.error("Could not record the Codex hook scope; the Codex hook was not installed. Fix ~/.hilos permissions and rerun this command.");
+      process.exitCode = 1;
+    } else {
+      const installed = installHooksFile({
+        target: globalTarget,
+        merge: (settings) => mergeCodexHooksIntoSettings(settings, commands.codex),
+        label: "Codex",
+        scope: isGlobal ? "Every" : "This repo's opted-in",
+      });
+      if (!installed) {
+        // The scope is authority state. If the executable hook could not be
+        // installed, restore it exactly so an old project hook is not disabled
+        // merely because an unrelated home hooks.json was malformed.
+        try {
+          if (scopeExisted && priorScope) {
+            writeFileSync(CODEX_HOOK_SCOPE_FILE, priorScope, { mode: 0o600 });
+            chmodSync(CODEX_HOOK_SCOPE_FILE, 0o600);
+          } else if (!scopeExisted) {
+            unlinkSync(CODEX_HOOK_SCOPE_FILE);
+          }
+        } catch {
+          console.error("Could not restore the prior Codex hook scope after the install failed.");
+          process.exitCode = 1;
+        }
+      } else {
+        // `codex exec` currently skips repository hooks while the TUI runs
+        // them. One global hook + our allowlist covers both and avoids double
+        // sends in the TUI. Migrate the pre-0854 project entry in place.
+        const projectTarget = join(codexProjectPath(process.cwd()), ".codex", "hooks.json");
+        if (normalizedProjectPath(projectTarget) !== normalizedProjectPath(globalTarget)) {
+          removeProjectCodexHook(projectTarget);
+        }
+        if (!isGlobal) {
+          console.log(`Allowed Codex hooks only for ${codexProjectPath(process.cwd())}.`);
+        }
+        console.log("Codex asks you to review this hook once; open /hooks and trust the hilos entry.");
+      }
+    }
   }
   if (client !== "claude" && client !== "codex") {
     installHooksFile({
       target: isGlobal
         ? join(homedir(), ".cursor", "hooks.json")
         : join(process.cwd(), ".cursor", "hooks.json"),
-      merge: mergeCursorHooksIntoSettings,
+      merge: (settings) => mergeCursorHooksIntoSettings(settings, commands.cursor),
       label: "Cursor",
       scope,
     });
   }
   console.log("Kill switches: HILOS_HOOKS=off pauses streaming; HILOS_REPLY_BRIDGE=off pauses reply pickup.");
-  // The installed entry runs `hilos-agent hook` directly (npx per tool call
-  // would add cold-start latency) — warn now if that won't resolve.
-  const onPath = (process.env.PATH || "")
-    .split(delimiter)
-    .some((dir) => dir && existsSync(join(dir, "hilos-agent")));
-  if (!onPath) {
-    console.log(
-      "NOTE: hilos-agent isn't on your PATH — the hooks won't fire until you run: npm i -g hilos-agent",
-    );
-  }
+  console.log(`Private hook runtime: ${runtime}. No global hilos-agent install is required.`);
 }