hilos-agent 0.7.0 → 0.9.1

package/src/hook.mjs

@@ -1,26 +1,27 @@
-// 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: `hooks install` writes project-local
+//     Codex, Claude, and Cursor hook files, so only repos you opt in ever stream.
+//     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 } 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 { sanitizeText, webTarget } from "./agent-events.mjs";
 import { resolveConfig } from "./config.mjs";
 
 export const HOOK_STATE_DIR = join(homedir(), ".hilos", "hook-state");
@@ -35,29 +36,183 @@ const MAX_FILES = 20;
 const STATE_TTL_MS = 48 * 60 * 60 * 1000;
 
 /**
- * Parse a Claude Code hook event from stdin text. Returns a normalized
- * { event, sessionId, toolName, toolInput, cwd } or null when unusable.
+ * 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 || !/hilos/i.test(match[1])) 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 : "";
+  // 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,
+    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 || "";
+  out.connectionKey = hookConnectionKey(token);
+  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 +252,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 +262,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 +340,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 */
   }
@@ -211,7 +374,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 +395,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 +415,77 @@ 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
+  if (!url || !token) return; // not connected to hilos — no-op
+
+  let state = sessionState(readState(ev.sessionId, stateDir), 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 (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) {
+  if (!state.startedAt) {
     gcStateDir(stateDir, now()); // new session — a cheap moment to sweep old ones
-    state = { startedAt: now(), lastSentAt: 0, steps: [], files: [], messageId: null };
+    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 +499,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 +540,13 @@ 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" } = {}) {
   try {
     if (/^(off|0|false)$/i.test(process.env.HILOS_HOOKS || "")) return;
     const raw = await readStdin();
     const cfg = resolveConfig({});
-    await runHook({ raw, cfg });
+    await runHook({ raw, cfg, vendor });
   } catch {
     /* a hook must never fail the user's CLI */
   }
@@ -341,33 +554,98 @@ 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 CODEX_HOOK_COMMAND = "hilos-agent hook --vendor codex";
+const CURSOR_HOOK_COMMAND = "hilos-agent hook --vendor cursor";
 
 /** The hooks block hilos needs inside a Claude Code settings.json. */
 export function hilosHooksBlock() {
-  const entry = { hooks: [{ type: "command", command: HOOK_COMMAND }] };
+  const entry = { hooks: [{ type: "command", command: CLAUDE_HOOK_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() {
+  const entry = { hooks: [{ type: "command", command: CODEX_HOOK_COMMAND, timeout: 5 }] };
+  const sessionEnd = { hooks: [{ type: "command", command: CODEX_HOOK_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() {
+  const entry = { command: CURSOR_HOOK_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) {
+  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 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") {
+          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) {
+  return mergeHookBlock(settings, hilosHooksBlock(), CLAUDE_HOOK_COMMAND);
+}
+
+export function mergeCodexHooksIntoSettings(settings) {
+  return mergeHookBlock(settings, hilosCodexHooksBlock(), CODEX_HOOK_COMMAND);
+}
+
+export function mergeCursorHooksIntoSettings(settings) {
   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 : {});
-  let changed = false;
-  for (const [event, entries] of Object.entries(hilosHooksBlock())) {
+  for (const [event, entries] of Object.entries(hilosCursorHooksBlock())) {
     const existing = Array.isArray(hooks[event]) ? hooks[event] : [];
-    const already = existing.some((e) =>
-      (e?.hooks || []).some((h) => h?.command === HOOK_COMMAND),
-    );
-    if (!already) {
+    if (!existing.some((handler) => handler?.command === CURSOR_HOOK_COMMAND)) {
       hooks[event] = [...existing, ...entries];
       changed = true;
     }
@@ -376,19 +654,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");
+function installHooksFile({ target, merge, label, scope }) {
   let current = {};
   if (existsSync(target)) {
     try {
@@ -396,24 +662,75 @@ 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}.`);
-    return;
+    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");
-  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.");
+  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;
+}
+
+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):");
+      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 (sub !== "install") {
+    console.log("Usage: hilos-agent hooks <install|print> [--global] [--claude|--codex|--cursor]");
+    return;
+  }
+  const scope = isGlobal ? "Every opted-in" : "This repo's";
+  if (client !== "codex" && client !== "cursor") {
+    installHooksFile({
+      target: isGlobal
+        ? join(homedir(), ".claude", "settings.json")
+        : join(process.cwd(), ".claude", "settings.json"),
+      merge: mergeHooksIntoSettings,
+      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.");
+  }
+  if (client !== "claude" && client !== "codex") {
+    installHooksFile({
+      target: isGlobal
+        ? join(homedir(), ".cursor", "hooks.json")
+        : join(process.cwd(), ".cursor", "hooks.json"),
+      merge: mergeCursorHooksIntoSettings,
+      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 || "")