hilos-agent 0.9.0 → 0.9.2

package/src/hook.mjs

@@ -1,29 +1,34 @@
-// Claude Code hook → hilos live progress (0448). This is the "watch your
-// agent's hands move" path for a RAW CLI session (no daemon): install the
-// hilos hooks in a repo (`hilos-agent hooks install`) and every tool call your
-// Claude Code session makes streams a step into the agent's live status card
-// in its hilos channel, via the `post_progress` MCP tool's channelId mode.
+// Local coding-session hooks → hilos live progress (0448) + thread binding
+// (0847). This is the "watch your agent's hands move" path for a raw Codex,
+// Claude Code, or Cursor session. Every tool call can stream a step into the agent's live
+// card; a successful hilos post also binds that provider session to the exact
+// hilos thread so the daemon can carry a later human reply back into it.
 //
 // Design rules:
 //   - NEVER block or break the user's CLI. Every entry point swallows every
 //     error and exits 0; the network send is capped by a hard timeout.
-//   - Cheap by default: a state file per Claude session carries the message id,
+//   - Cheap by default: a state file per provider session carries the message id,
 //     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 to the PROJECT's
-//     .claude/settings.json, so only repos you opt in ever stream. HILOS_HOOKS=off
-//     is the global kill switch.
+//   - 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 } 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 { sanitizeText } from "./agent-events.mjs";
+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. */
@@ -34,30 +39,322 @@ 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()),
+  );
+}
+
 /**
- * Parse a Claude Code hook event from stdin text. Returns a normalized
- * { event, sessionId, toolName, toolInput, cwd } or null when unusable.
+ * 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
+ * global hook-state directory alone is not an authority boundary.
+ */
+export function hookConnectionKey(token) {
+  const value = typeof token === "string" ? token.trim() : "";
+  return value ? createHash("sha256").update(value).digest("hex").slice(0, 24) : "";
+}
+
+/**
+ * Parse a Codex / Claude Code / Cursor hook event from stdin text. Returns a
+ * normalized event or null when unusable. The providers share common fields;
+ * toolResponse is additive for PostToolUse and ignored by the progress lane.
  * PURE — never throws.
  */
 export function parseHookEvent(raw) {
   try {
     const o = JSON.parse(String(raw));
     if (!o || typeof o !== "object") return null;
-    const event = typeof o.hook_event_name === "string" ? o.hook_event_name : "";
-    const sessionId = typeof o.session_id === "string" ? o.session_id : "";
+    const rawEvent = typeof o.hook_event_name === "string" ? o.hook_event_name : "";
+    const event = ({
+      sessionStart: "SessionStart",
+      beforeSubmitPrompt: "UserPromptSubmit",
+      postToolUse: "PostToolUse",
+      afterMCPExecution: "PostToolUse",
+      stop: "Stop",
+      sessionEnd: "SessionEnd",
+    })[rawEvent] || rawEvent;
+    const cursorEvent = Object.hasOwn({
+      sessionStart: true,
+      beforeSubmitPrompt: true,
+      postToolUse: true,
+      afterMCPExecution: true,
+      stop: true,
+      sessionEnd: true,
+    }, rawEvent);
+    // Cursor's resumable chat id is conversation_id. Some lifecycle payloads
+    // also carry a hook/session id; preferring that would write the anchor under
+    // an identifier `cursor-agent --resume` does not accept.
+    const sessionId = cursorEvent && typeof o.conversation_id === "string"
+      ? o.conversation_id
+      : typeof o.session_id === "string"
+        ? o.session_id
+        : typeof o.conversation_id === "string"
+          ? o.conversation_id
+          : "";
     if (!event || !sessionId) return null;
+    const jsonObject = (value) => {
+      if (value && typeof value === "object") return value;
+      if (typeof value !== "string") return {};
+      try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === "object" ? parsed : {};
+      } catch {
+        return {};
+      }
+    };
+    const cursorMcp = rawEvent === "afterMCPExecution";
+    const server = typeof o.mcp_server_name === "string" ? o.mcp_server_name : "";
+    const rawToolName = typeof o.tool_name === "string" ? o.tool_name : "";
     return {
       event,
       sessionId,
-      toolName: typeof o.tool_name === "string" ? o.tool_name : "",
-      toolInput: o.tool_input && typeof o.tool_input === "object" ? o.tool_input : {},
-      cwd: typeof o.cwd === "string" ? o.cwd : "",
+      toolName: cursorMcp && server && rawToolName
+        ? `mcp__${server}__${rawToolName}`
+        : rawToolName,
+      toolInput: jsonObject(o.tool_input),
+      ...(o.tool_response !== undefined
+        ? { toolResponse: o.tool_response }
+        : o.tool_output !== undefined
+          ? { toolResponse: o.tool_output }
+          : o.result_json !== undefined
+            ? { toolResponse: o.result_json }
+            : {}),
+      cwd: typeof o.cwd === "string"
+        ? o.cwd
+        : Array.isArray(o.workspace_roots) && typeof o.workspace_roots[0] === "string"
+          ? o.workspace_roots[0]
+          : "",
     };
   } catch {
     return null;
   }
 }
 
+/** A JSON-looking MCP text block, direct payload, or nested tool result. */
+export function mcpResponsePayload(value, depth = 0) {
+  if (depth > 5 || value == null) return null;
+  if (typeof value === "string") {
+    try {
+      return mcpResponsePayload(JSON.parse(value), depth + 1);
+    } catch {
+      return null;
+    }
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const found = mcpResponsePayload(item, depth + 1);
+      if (found) return found;
+    }
+    return null;
+  }
+  if (typeof value !== "object") return null;
+  if (typeof value.messageId === "string") return value;
+  if (typeof value.text === "string") {
+    const parsed = mcpResponsePayload(value.text, depth + 1);
+    if (parsed) return parsed;
+  }
+  for (const key of ["structuredContent", "content", "result", "output"]) {
+    const found = mcpResponsePayload(value[key], depth + 1);
+    if (found) return found;
+  }
+  return null;
+}
+
+/**
+ * A successful hilos post made by this local session becomes its reply anchor.
+ * Match the hilos MCP server segment as well as the tool suffix so another MCP
+ * server's coincidentally named post_message can never bind a hilos session.
+ */
+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) 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.
+  if (!messageId || !agentId) return null;
+  const parentId = typeof ev.toolInput?.parentId === "string" ? ev.toolInput.parentId : "";
+  return {
+    threadRootId: parentId || messageId,
+    anchorMessageId: messageId,
+    channelId,
+    agentId,
+    ...(bindingClaim ? { bindingClaim } : {}),
+    boundAt: at,
+    processedReplyIds: [],
+  };
+}
+
+/** Keep the newest anchor for a thread and preserve already-processed replies. */
+export function upsertBinding(state, binding, limit = 8) {
+  if (!state || !binding?.threadRootId || !binding?.anchorMessageId) return state;
+  const current = Array.isArray(state.bindings) ? state.bindings : [];
+  const prior = current.find((item) => item?.threadRootId === binding.threadRootId);
+  const next = {
+    ...binding,
+    processedReplyIds: Array.isArray(prior?.processedReplyIds)
+      ? prior.processedReplyIds.slice(-100)
+      : Array.isArray(binding.processedReplyIds)
+        ? binding.processedReplyIds.slice(-100)
+        : [],
+  };
+  state.bindings = [
+    ...current.filter((item) => item?.threadRootId !== binding.threadRootId),
+    next,
+  ].slice(-limit);
+  return state;
+}
+
+function sessionState(state, ev, vendor, now, token) {
+  const out = state && typeof state === "object"
+    ? state
+    : { startedAt: now(), lastSentAt: 0, steps: [], files: [], messageId: null };
+  out.sessionId = ev.sessionId;
+  out.vendor = vendor || out.vendor || "unknown";
+  out.cwd = ev.cwd || out.cwd || "";
+  // 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;
+}
+
 /** Strip the session cwd prefix so step labels read as repo-relative paths. */
 function relPath(p, cwd) {
   const s = String(p || "");
@@ -97,7 +394,8 @@ export function hookStep(toolName, toolInput, cwd = "") {
       return file ? { label: `Editing ${file}`, file } : { label: "Editing files" };
     case "Read":
       return file ? { label: `Reading ${file}`, file } : { label: "Reading files" };
-    case "Bash": {
+    case "Bash":
+    case "Shell": {
       const c = cmdLabel(input.command);
       return { label: c ? `Running ${c}` : "Running a command" };
     }
@@ -106,22 +404,26 @@ export function hookStep(toolName, toolInput, cwd = "") {
       const q = typeof input.pattern === "string" ? input.pattern : "";
       return { label: q ? `Searching for ${q.slice(0, 60)}` : "Searching the repo" };
     }
+    // `Agent` is what Claude Code 2.1.233 calls the subagent tool; `Task` is the
+    // older name. Before 0789 only `Task` was here, so a spawn on a current
+    // build fell through to the default arm and narrated "Using Agent".
+    case "Agent":
     case "Task": {
       const d = typeof input.description === "string" ? input.description : "";
-      return { label: d ? `Delegating: ${d.slice(0, 60)}` : "Delegating a task" };
+      // Same sentence the stream mappers emit (0789) — one room, one wording,
+      // whichever lane the run came through.
+      return { label: d ? `Started a helper: ${d.slice(0, 60)}` : "Started a helper" };
     }
     case "WebFetch": {
-      let host = "";
-      try {
-        host = new URL(String(input.url || "")).host;
-      } catch {
-        /* not a url */
-      }
-      return { label: host ? `Fetching ${host}` : "Fetching a page" };
+      // webTarget (0789) keeps host + PATH and drops the query string, the
+      // fragment, and userinfo, so a signed URL's token can't ride a hook step
+      // into the room.
+      const target = webTarget(input.url);
+      return { label: target ? `Read ${target}` : "Read a web page" };
     }
     case "WebSearch": {
       const q = typeof input.query === "string" ? input.query : "";
-      return { label: q ? `Searching the web: ${q.slice(0, 60)}` : "Searching the web" };
+      return { label: q ? `Searched the web: ${q.slice(0, 60)}` : "Searched the web" };
     }
     case "TodoWrite":
       return null; // planning chatter — too noisy to narrate
@@ -180,8 +482,11 @@ export function readState(sessionId, dir = HOOK_STATE_DIR) {
 
 export function writeState(sessionId, state, dir = HOOK_STATE_DIR) {
   try {
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(statePath(sessionId, dir), JSON.stringify(state));
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+    const path = statePath(sessionId, dir);
+    writeFileSync(path, JSON.stringify(state), { mode: 0o600 });
+    chmodSync(path, 0o600);
   } catch {
     /* best-effort */
   }
@@ -195,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);
@@ -211,7 +519,7 @@ export function gcStateDir(dir = HOOK_STATE_DIR, now = Date.now()) {
   }
 }
 
-/** One bounded post_progress call. Returns the server's messageId, or null. */
+/** One bounded post_progress call. Returns its authenticated anchor, or null. */
 async function sendProgress({ url, token, messageId, channelId, progress }) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
@@ -232,7 +540,15 @@ async function sendProgress({ url, token, messageId, channelId, progress }) {
     const json = await res.json();
     const text = json?.result?.content?.[0]?.text;
     const parsed = typeof text === "string" ? JSON.parse(text) : null;
-    return parsed && typeof parsed.messageId === "string" ? parsed.messageId : null;
+    // Older hilos servers do not return agentId yet. Keep progress-card reuse
+    // backward compatible, but refuse to turn that unauthenticated result into
+    // a reply binding below.
+    return parsed && typeof parsed.messageId === "string"
+      ? {
+          messageId: parsed.messageId,
+          agentId: typeof parsed.agentId === "string" ? parsed.agentId : "",
+        }
+      : null;
   } catch {
     return null;
   } finally {
@@ -244,47 +560,86 @@ async function sendProgress({ url, token, messageId, channelId, progress }) {
  * Handle one hook invocation end to end. Reads nothing from process.* so the
  * caller (bin) owns stdin/env; returns quietly on every failure path.
  */
-export async function runHook({ raw, cfg, now = Date.now, stateDir = HOOK_STATE_DIR }) {
+export async function runHook({ raw, cfg, vendor = "unknown", now = Date.now, stateDir = HOOK_STATE_DIR }) {
   const ev = parseHookEvent(raw);
   if (!ev) return;
   const { url, token, channelId } = cfg;
-  if (!url || !token || !channelId) return; // not connected to hilos — no-op
+
+  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);
+
+  if (ev.event === "SessionStart") {
+    state.active = false;
+    writeState(ev.sessionId, state, stateDir);
+    return;
+  }
+
+  if (ev.event === "UserPromptSubmit") {
+    state.active = true;
+    writeState(ev.sessionId, state, stateDir);
+    return;
+  }
 
   if (ev.event === "Stop" || ev.event === "SessionEnd") {
     // End of a turn (or the session): settle the card honestly — "not doing
     // 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.
-    const state = readState(ev.sessionId, stateDir);
-    if (!state || !state.messageId) return;
-    await sendProgress({
-      url,
-      token,
-      messageId: state.messageId,
-      progress: {
-        state: "done",
-        elapsedMs: Math.max(0, now() - (state.startedAt || now())),
-      },
-    });
-    if (ev.event === "SessionEnd") deleteState(ev.sessionId, stateDir);
-    else {
-      state.lastSentAt = now();
-      writeState(ev.sessionId, state, stateDir);
+    state.active = false;
+    if (url && token && state.messageId) {
+      await sendProgress({
+        url,
+        token,
+        messageId: state.messageId,
+        progress: {
+          state: "done",
+          elapsedMs: Math.max(0, now() - (state.startedAt || now())),
+        },
+      });
     }
+    // A provider SessionEnd does not make its id unresumable. Keep the local
+    // binding until the normal 48h GC so a reply received after the terminal
+    // window closes can still continue it.
+    state.lastSentAt = now();
+    writeState(ev.sessionId, state, stateDir);
     return;
   }
 
   if (ev.event !== "PostToolUse") return;
 
+  state.active = true;
+
   const step = hookStep(ev.toolName, ev.toolInput, ev.cwd);
-  if (!step) return;
+  if (!step) {
+    // hilos MCP calls are deliberately not narrated as progress, but their
+    // returned message id is the most important state this hook records.
+    writeState(ev.sessionId, state, stateDir);
+    return;
+  }
 
-  let state = readState(ev.sessionId, stateDir);
-  if (!state) {
-    gcStateDir(stateDir, now()); // new session — a cheap moment to sweep old ones
-    state = { startedAt: now(), lastSentAt: 0, steps: [], files: [], messageId: null };
+  // 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
+  // in any accessible room; it simply has nowhere to create an ambient card.
+  if (!channelId && !state.messageId) {
+    writeState(ev.sessionId, state, stateDir);
+    return;
+  }
+
   if (!shouldSendNow(state, now())) {
     // Inside the coalesce window: fold only. The next event (or Stop) flushes.
     writeState(ev.sessionId, state, stateDir);
@@ -298,19 +653,31 @@ export async function runHook({ raw, cfg, now = Date.now, stateDir = HOOK_STATE_
     filesTouched: state.files,
     elapsedMs: Math.max(0, now() - (state.startedAt || now())),
   };
-  const messageId = await sendProgress({
+  const anchor = await sendProgress({
     url,
     token,
     messageId: state.messageId || undefined,
     channelId,
     progress,
   });
-  if (messageId) state.messageId = messageId;
+  if (anchor) {
+    state.messageId = anchor.messageId;
+    if (channelId && anchor.agentId) {
+      upsertBinding(state, {
+        threadRootId: anchor.messageId,
+        anchorMessageId: anchor.messageId,
+        channelId,
+        agentId: anchor.agentId,
+        boundAt: new Date(now()).toISOString(),
+        processedReplyIds: [],
+      });
+    }
+  }
   state.lastSentAt = now();
   writeState(ev.sessionId, state, stateDir);
 }
 
-/** Read all of stdin (the hook event JSON Claude Code pipes in). */
+/** Read all of stdin (the hook event JSON the coding tool pipes in). */
 function readStdin() {
   return new Promise((resolve) => {
     let data = "";
@@ -327,13 +694,27 @@ function readStdin() {
   });
 }
 
-/** `hilos-agent hook` — the command Claude Code invokes. Always exits 0. */
-export async function hookMain() {
+/** `hilos-agent hook` — the command each provider invokes. Always exits 0. */
+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 });
+    await runHook({ raw, cfg, vendor });
   } catch {
     /* a hook must never fail the user's CLI */
   }
@@ -341,33 +722,230 @@ export async function hookMain() {
 
 // --- `hilos-agent hooks print|install [--global]` ---------------------------
 
-const HOOK_COMMAND = "hilos-agent hook";
+const CLAUDE_HOOK_COMMAND = "hilos-agent hook --vendor claude_code";
+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: 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],
     PostToolUse: [{ matcher: "*", ...entry }],
     Stop: [entry],
     SessionEnd: [entry],
   };
 }
 
+/** The equivalent project/global hooks file Codex discovers in `.codex/`. */
+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],
+    PostToolUse: [{ matcher: "*", ...entry }],
+    Stop: [entry],
+    SessionEnd: [sessionEnd],
+  };
+}
+
+/** Cursor's native hooks.json uses lower-camel event names and flat commands. */
+export function hilosCursorHooksBlock(command = CURSOR_HOOK_COMMAND) {
+  const entry = { command, timeout: 5 };
+  return {
+    sessionStart: [entry],
+    beforeSubmitPrompt: [entry],
+    postToolUse: [entry],
+    // This event carries mcp_server_name + the full result; postToolUse alone
+    // has no server identity on Cursor 2026.07.23.
+    afterMCPExecution: [entry],
+    stop: [entry],
+    sessionEnd: [entry],
+  };
+}
+
+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;
+  for (const [event, entries] of Object.entries(block)) {
+    const existing = Array.isArray(hooks[event]) ? hooks[event] : [];
+    let found = false;
+    for (const group of existing) {
+      for (const handler of group?.hooks || []) {
+        if (handler?.command === command) found = true;
+        // 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;
+        }
+      }
+    }
+    if (!found) {
+      hooks[event] = [...existing, ...entries];
+      changed = true;
+    }
+  }
+  return { settings: out, changed };
+}
+
 /**
  * Idempotently merge the hilos hooks into a settings object (parsed
  * settings.json). Existing user hooks are preserved; a second install is a
  * no-op. PURE — returns { settings, changed }.
  */
-export function mergeHooksIntoSettings(settings) {
+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, 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 = out.hooks && typeof out.hooks === "object" ? out.hooks : {});
+  const hooks = out.hooks && typeof out.hooks === "object" ? out.hooks : {};
   let changed = false;
-  for (const [event, entries] of Object.entries(hilosHooksBlock())) {
+  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, 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(command))) {
     const existing = Array.isArray(hooks[event]) ? hooks[event] : [];
-    const already = existing.some((e) =>
-      (e?.hooks || []).some((h) => h?.command === HOOK_COMMAND),
-    );
-    if (!already) {
+    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;
     }
@@ -376,19 +954,7 @@ export function mergeHooksIntoSettings(settings) {
 }
 
 /** `hilos-agent hooks install [--global]` / `hilos-agent hooks print`. */
-export function hooksMain(sub, { global: isGlobal = false } = {}) {
-  if (sub === "print") {
-    console.log(JSON.stringify({ hooks: hilosHooksBlock() }, null, 2));
-    console.log("\nMerge this into .claude/settings.json in the repo you want to stream.");
-    return;
-  }
-  if (sub !== "install") {
-    console.log("Usage: hilos-agent hooks <install|print> [--global]");
-    return;
-  }
-  const target = isGlobal
-    ? join(homedir(), ".claude", "settings.json")
-    : join(process.cwd(), ".claude", "settings.json");
+export function installHooksFile({ target, merge, label, scope }) {
   let current = {};
   if (existsSync(target)) {
     try {
@@ -396,32 +962,151 @@ export function hooksMain(sub, { global: isGlobal = false } = {}) {
     } catch {
       console.error(`${target} exists but isn't valid JSON — fix it first (nothing written).`);
       process.exitCode = 1;
-      return;
+      return false;
     }
   }
-  const { settings, changed } = mergeHooksIntoSettings(current);
+  const { settings, changed } = merge(current);
   if (!changed) {
-    console.log(`hilos hooks already installed in ${target}.`);
+    console.log(`${label} hilos hooks already installed in ${target}.`);
+    return true;
+  }
+  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") {
+      console.log("Claude Code (.claude/settings.json):");
+      console.log(JSON.stringify({ hooks: hilosHooksBlock() }, null, 2));
+    }
+    if (client !== "claude" && client !== "cursor") {
+      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") {
+      console.log("\nCursor (.cursor/hooks.json):");
+      console.log(JSON.stringify({ version: 1, hooks: hilosCursorHooksBlock() }, null, 2));
+    }
     return;
   }
-  if (existsSync(target)) writeFileSync(target + ".bak", readFileSync(target));
-  mkdirSync(dirname(target), { recursive: true });
-  writeFileSync(target, JSON.stringify(settings, null, 2) + "\n");
-  console.log(`Installed hilos hooks into ${target}${existsSync(target + ".bak") ? ` (backup: ${target}.bak)` : ""}.`);
-  console.log(
-    isGlobal
-      ? "Every Claude Code session on this machine will now stream its steps to your hilos channel."
-      : "Claude Code sessions in THIS repo will now stream their steps to your hilos channel.",
-  );
-  console.log("Kill switch: HILOS_HOOKS=off.");
-  // 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",
-    );
+  if (sub !== "install") {
+    console.log("Usage: hilos-agent hooks <install|print> [--global] [--claude|--codex|--cursor]");
+    return;
+  }
+  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: (settings) => mergeHooksIntoSettings(settings, commands.claude),
+      label: "Claude Code",
+      scope,
+    });
+  }
+  if (client !== "claude" && client !== "cursor") {
+    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: (settings) => mergeCursorHooksIntoSettings(settings, commands.cursor),
+      label: "Cursor",
+      scope,
+    });
   }
+  console.log("Kill switches: HILOS_HOOKS=off pauses streaming; HILOS_REPLY_BRIDGE=off pauses reply pickup.");
+  console.log(`Private hook runtime: ${runtime}. No global hilos-agent install is required.`);
 }