@halofy/agent-connect 0.1.0 → 0.2.0

package/README.md

@@ -14,35 +14,56 @@ agent connections:
 - signed heartbeat, open, append, recall, context-use, commit, status, and
   close transport methods;
 - a stdio-to-signed-Streamable-HTTP MCP proof proxy; and
-- the local claim consumer used by the Claude Code adapter.
+- one local claim consumer and proof runtime shared by every packaged adapter.
 
-The one supported Claude Code setup path is the lifecycle installer:
+There is one setup path for every packaged client:
 
 ```bash
-npx --yes @halofy/agent-connect@0.1.0 install claude-code \
+npx --yes @halofy/agent-connect@0.2.0 install <client-kind> \
   --server https://app.halofy.ai \
   --claim '<one-time-claim>'
 ```
 
+The server, not the browser, selects the exact published package version and
+permits only these reviewed client kinds:
+
+| Client kind | Adapter coverage | Explicit current gaps |
+|---|---|---|
+| `claude-code` | complete for declared text/tool lifecycle hooks | image bodies, artifact bodies, context-use evidence |
+| `cursor` | complete for declared text/tool lifecycle hooks | image bodies, artifact bodies, context-use evidence |
+| `gemini-cli` | complete for declared text/tool lifecycle hooks | image bodies, artifact bodies, subagents, context-use evidence |
+| `codex` | partial | assistant responses, tool failures, session end, binary bodies |
+| `vscode` | partial | assistant responses, binary bodies, context-use evidence |
+| `cline` | partial | assistant responses, tool failures, subagents, compaction, session end, binary bodies |
+
+Other catalog entries remain `Not supported yet` or `Not observed`; the
+installer refuses them before claim consumption. A knowledge connector,
+OAuth-only MCP connection, legacy bearer, or manual MCP URL is never upgraded
+to conversation-capture evidence by its name.
+
 Run the server-returned command in the operating-system terminal from the
-project where Claude Code runs, never in agent chat. The installer displays
+computer where the selected client runs, never in agent chat. The installer displays
 the capture disclosure, requires the recipient to type `CONNECT`, generates
 the Ed25519 private key locally, consumes the one-use claim in a JSON body,
 copies the reviewed runtime out of the transient npx cache, and installs the
 signed MCP proxy and lifecycle hooks together. It replaces an existing Halofy
-bearer MCP entry and legacy Halofy hooks in place while preserving unrelated
-Claude settings. It never runs both Halofy capture paths for one host session.
+bearer MCP entry where the host exposes one and installs its reviewed hooks
+while preserving unrelated settings. It never runs both Halofy capture paths
+for one host session.
 
 The current storage backend is the explicitly reported mode-`0600` file
 fallback (or the closest Windows ACL), not hardware-backed storage. No bearer
-or claim is stored in the runtime queue or Claude configuration.
+or claim is stored in the runtime queue or host configuration.
 
 The request canonicalization in `src/crypto.mjs` follows AL4's strict raw path
 and query rules. Publication is fail-closed until the package tarball, current
 Claude fixtures, cross-implementation signature fixtures, and deployed server
-protocol have all passed for the exact version.
+protocol have all passed for the exact version. Server versions configured
+with the Claude-only `0.1.x` artifact keep every additional client fenced as
+`Not supported yet`.
 
-The Claude adapter advertises archive protocol v1 explicitly. Its current
+Every packaged adapter advertises archive protocol v1 explicitly. The Claude
+adapter's current
 body capabilities are user/assistant text, structured tool inputs/results and
 failures, and host artifact references. Inline images and artifact bodies are
 represented by digest-only placeholders and make coverage partial;

package/bin/halofy-agent.mjs

@@ -4,6 +4,7 @@ import { loadActiveConnection } from "../src/active.mjs";
 import { runStdioMcpProxy } from "../src/mcp-proxy.mjs";
 import { BoundedEncryptedQueue } from "../src/queue.mjs";
 import { runClaudeLifecycleHook } from "../src/claude-hook.mjs";
+import { HOST_HOOK_EVENTS, runHostLifecycleHook } from "../src/host-hook.mjs";
 import { join } from "node:path";
 
 function option(name) {
@@ -13,12 +14,12 @@ function option(name) {
 
 const command = process.argv[2];
 const hookEvent = command === "hook" ? process.argv[3] : null;
-const hookEvents = new Set([
+const claudeHookEvents = new Set([
   "SessionStart", "UserPromptSubmit", "Stop", "PreCompact", "SessionEnd",
   "SubagentStart", "SubagentStop", "PostToolUse", "PostToolUseFailure", "PostToolBatch",
 ]);
 if (!["mcp", "diagnostics", "hook"].includes(command) ||
-    (command === "hook" && !hookEvents.has(hookEvent))) {
+    (command === "hook" && !claudeHookEvents.has(hookEvent) && !HOST_HOOK_EVENTS.has(hookEvent))) {
   process.stderr.write("Usage: halofy-agent <mcp|diagnostics|hook EVENT> [--connection <installation-id>]\n");
   process.exitCode = 2;
 } else {
@@ -31,7 +32,8 @@ if (!["mcp", "diagnostics", "hook"].includes(command) ||
     if (command === "mcp") {
       await runStdioMcpProxy(connection);
     } else if (command === "hook") {
-      await runClaudeLifecycleHook(connection, hookEvent);
+      if (connection.clientKind === "claude-code") await runClaudeLifecycleHook(connection, hookEvent);
+      else await runHostLifecycleHook(connection, hookEvent);
     } else {
       const queue = new BoundedEncryptedQueue(join(defaultRuntimeDirectory(), connection.installationId));
       process.stdout.write(`${JSON.stringify({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halofy/agent-connect",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Signed Halofy lifecycle installer and runtime for supported agents",
   "bin": {

package/src/claude-hook.mjs

@@ -8,12 +8,23 @@ function id(value) {
   return createHash("sha256").update(String(value)).digest("hex");
 }
 
-export function readHookInput(stream = process.stdin) {
+export function readHookInput(stream = process.stdin, maxBytes = 1024 * 1024) {
   return new Promise((resolve) => {
     let raw = "";
+    let bytes = 0;
+    let oversized = false;
     stream.setEncoding("utf8");
-    stream.on("data", (chunk) => { raw += chunk; });
+    stream.on("data", (chunk) => {
+      bytes += Buffer.byteLength(chunk, "utf8");
+      if (bytes > maxBytes) {
+        oversized = true;
+        raw = "";
+        return;
+      }
+      if (!oversized) raw += chunk;
+    });
     stream.on("end", () => {
+      if (oversized) return resolve({});
       try { resolve(JSON.parse(raw)); } catch { resolve({}); }
     });
     stream.on("error", () => resolve({}));
@@ -57,10 +68,15 @@ async function catchUp(runtime, input, session = hostSession(input)) {
 }
 
 async function within(milliseconds, action) {
-  return Promise.race([
-    action(),
-    new Promise((resolve) => setTimeout(() => resolve(null), milliseconds)),
-  ]);
+  let timer;
+  try {
+    return await Promise.race([
+      action(),
+      new Promise((resolve) => { timer = setTimeout(() => resolve(null), milliseconds); }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
 }
 
 /** Runs one reviewed Claude hook. Brownouts never block the host session. */

package/src/client-registry.mjs

@@ -0,0 +1,128 @@
+export const CLIENT_KINDS = Object.freeze([
+  "claude-code",
+  "codex",
+  "cursor",
+  "vscode",
+  "cline",
+  "gemini-cli",
+]);
+
+const BASE_CAPABILITIES = Object.freeze({
+  sessionStart: false,
+  userPromptSubmit: false,
+  stop: false,
+  preCompact: false,
+  sessionEnd: false,
+  subagentStart: false,
+  subagentStop: false,
+  postToolUse: false,
+  postToolUseFailure: false,
+  postToolBatch: false,
+  conversationArchive: true,
+  archiveProtocolV1: true,
+  userMessages: false,
+  assistantMessages: false,
+  toolInputs: false,
+  toolOutputs: false,
+  toolFailures: false,
+  images: false,
+  contextUseEvidence: false,
+  artifactBodies: false,
+  artifactReferences: false,
+  subagents: false,
+  compactionCheckpoints: false,
+  contextRecalled: false,
+});
+
+function capabilities(overrides) {
+  return Object.freeze({ ...BASE_CAPABILITIES, ...overrides });
+}
+
+export const CLIENT_REGISTRY = Object.freeze({
+  "claude-code": Object.freeze({
+    clientKind: "claude-code",
+    label: "Claude Code",
+    command: "claude",
+    coverage: "complete",
+    capabilities: capabilities({
+      sessionStart: true, userPromptSubmit: true, stop: true, preCompact: true,
+      sessionEnd: true, subagentStart: true, subagentStop: true,
+      postToolUse: true, postToolUseFailure: true, postToolBatch: true,
+      userMessages: true, assistantMessages: true, toolInputs: true,
+      toolOutputs: true, toolFailures: true, artifactReferences: true,
+      subagents: true, compactionCheckpoints: true, contextRecalled: true,
+    }),
+  }),
+  cursor: Object.freeze({
+    clientKind: "cursor",
+    label: "Cursor",
+    command: "cursor",
+    coverage: "complete",
+    capabilities: capabilities({
+      sessionStart: true, userPromptSubmit: true, stop: true, preCompact: true,
+      sessionEnd: true, subagentStart: true, subagentStop: true,
+      postToolUse: true, postToolUseFailure: true, userMessages: true,
+      assistantMessages: true, toolInputs: true, toolOutputs: true,
+      toolFailures: true, artifactReferences: true, subagents: true,
+      compactionCheckpoints: true, contextRecalled: true,
+    }),
+  }),
+  "gemini-cli": Object.freeze({
+    clientKind: "gemini-cli",
+    label: "Gemini CLI",
+    command: "gemini",
+    coverage: "complete",
+    capabilities: capabilities({
+      sessionStart: true, userPromptSubmit: true, preCompact: true,
+      sessionEnd: true, postToolUse: true, postToolUseFailure: true,
+      userMessages: true, assistantMessages: true, toolInputs: true,
+      toolOutputs: true, toolFailures: true, artifactReferences: true,
+      compactionCheckpoints: true, contextRecalled: true,
+    }),
+  }),
+  vscode: Object.freeze({
+    clientKind: "vscode",
+    label: "VS Code",
+    command: "code",
+    coverage: "partial",
+    reason: "assistant_message_hook_unavailable",
+    capabilities: capabilities({
+      sessionStart: true, userPromptSubmit: true, stop: true, preCompact: true,
+      subagentStart: true, subagentStop: true, postToolUse: true,
+      postToolUseFailure: true, userMessages: true, toolInputs: true,
+      toolOutputs: true, toolFailures: true, subagents: true,
+      compactionCheckpoints: true, contextRecalled: true,
+    }),
+  }),
+  codex: Object.freeze({
+    clientKind: "codex",
+    label: "Codex CLI",
+    command: "codex",
+    coverage: "partial",
+    reason: "assistant_message_session_end_and_tool_failure_hooks_unavailable",
+    capabilities: capabilities({
+      sessionStart: true, userPromptSubmit: true, stop: true, preCompact: true,
+      subagentStart: true, subagentStop: true, postToolUse: true,
+      userMessages: true, toolInputs: true, toolOutputs: true, subagents: true,
+      compactionCheckpoints: true, contextRecalled: true,
+    }),
+  }),
+  cline: Object.freeze({
+    clientKind: "cline",
+    label: "Cline",
+    command: null,
+    coverage: "partial",
+    reason: "assistant_message_session_end_and_tool_failure_hooks_unavailable",
+    capabilities: capabilities({
+      sessionStart: true, userPromptSubmit: true, postToolUse: true,
+      userMessages: true, toolInputs: true, toolOutputs: true,
+      contextRecalled: true,
+    }),
+  }),
+});
+
+export function lifecycleClient(clientKind) {
+  const client = CLIENT_REGISTRY[String(clientKind || "")];
+  if (!client) throw new Error("unsupported lifecycle client");
+  return client;
+}

package/src/host-config.mjs

@@ -0,0 +1,292 @@
+import { chmod, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { ensurePrivateDirectory, readJson, writePrivateFile } from "./storage.mjs";
+
+function commandArg(value) {
+  const text = String(value);
+  if (/[^A-Za-z0-9_./:@+-]/.test(text)) {
+    if (/[\0\r\n"`$\\]/.test(text)) throw new Error("local integration path cannot be encoded safely for a host hook");
+    return `"${text}"`;
+  }
+  return text;
+}
+
+function managedCommand(nodePath, runtimePath, eventName, installationId) {
+  return [nodePath, runtimePath, "hook", eventName, "--connection", installationId].map(commandArg).join(" ");
+}
+
+function managedMcp(nodePath, runtimePath, installationId, { explicitType = false } = {}) {
+  return {
+    ...(explicitType ? { type: "stdio" } : {}),
+    command: resolve(nodePath),
+    args: [resolve(runtimePath), "mcp", "--connection", installationId],
+  };
+}
+
+function isManagedMcp(entry) {
+  return Array.isArray(entry?.args) && entry.args.some((value) =>
+    /halofy-agent\.mjs$/.test(String(value))) && entry.args.includes("--connection");
+}
+
+function replaceHalofyMcpEntries(registry, nextEntry) {
+  let replacedLegacyMcpEntries = 0;
+  for (const [name, entry] of Object.entries(registry)) {
+    if (!["halofy", "halomem"].includes(name.toLowerCase())) continue;
+    if (!isManagedMcp(entry)) replacedLegacyMcpEntries += 1;
+    delete registry[name];
+  }
+  registry.halofy = nextEntry;
+  return replacedLegacyMcpEntries;
+}
+
+function isManaged(entry) {
+  return /halofy-agent\.mjs\s+hook\s+/.test(String(entry?.command || entry?.hooks?.[0]?.command || ""));
+}
+
+function mergeFlatHooks(settings, definitions, registration) {
+  settings.hooks = settings.hooks && typeof settings.hooks === "object" ? settings.hooks : {};
+  for (const [hostEvent, runtimeEvent] of Object.entries(definitions)) {
+    const current = Array.isArray(settings.hooks[hostEvent]) ? settings.hooks[hostEvent] : [];
+    settings.hooks[hostEvent] = [...current.filter((entry) => !isManaged(entry)), registration(runtimeEvent)];
+  }
+}
+
+function validateInputs({ installationId, runtimePath }) {
+  if (!/^[A-Za-z0-9_-]{1,160}$/.test(String(installationId))) throw new Error("invalid installation id");
+  if (!runtimePath) throw new Error("installed runtime path is required");
+}
+
+const CURSOR_HOOKS = Object.freeze({
+  sessionStart: "sessionStart",
+  beforeSubmitPrompt: "beforeSubmitPrompt",
+  afterAgentResponse: "afterAgentResponse",
+  postToolUse: "postToolUse",
+  postToolUseFailure: "postToolUseFailure",
+  preCompact: "preCompact",
+  stop: "stop",
+  sessionEnd: "sessionEnd",
+  subagentStart: "subagentStart",
+  subagentStop: "subagentStop",
+});
+
+export async function configureCursor({
+  installationId,
+  nodePath = process.execPath,
+  runtimePath,
+  cursorRoot = join(homedir(), ".cursor"),
+}) {
+  validateInputs({ installationId, runtimePath });
+  const hooksPath = join(cursorRoot, "hooks.json");
+  const mcpPath = join(cursorRoot, "mcp.json");
+  const hooks = await readJson(hooksPath, {});
+  hooks.version = 1;
+  mergeFlatHooks(hooks, CURSOR_HOOKS, (eventName) => ({
+    command: managedCommand(nodePath, runtimePath, eventName, installationId),
+    timeout: 20,
+    failClosed: false,
+  }));
+  const mcp = await readJson(mcpPath, {});
+  mcp.mcpServers = mcp.mcpServers && typeof mcp.mcpServers === "object" ? mcp.mcpServers : {};
+  const replacedLegacyMcpEntries = replaceHalofyMcpEntries(
+    mcp.mcpServers,
+    managedMcp(nodePath, runtimePath, installationId),
+  );
+  await writePrivateFile(hooksPath, `${JSON.stringify(hooks, null, 2)}\n`);
+  await writePrivateFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
+  return { configuredPaths: [hooksPath, mcpPath], hookEvents: Object.keys(CURSOR_HOOKS), replacedLegacyMcpEntries };
+}
+
+const GEMINI_HOOKS = Object.freeze({
+  SessionStart: "SessionStart",
+  BeforeAgent: "BeforeAgent",
+  AfterAgent: "AfterAgent",
+  AfterTool: "AfterTool",
+  PreCompress: "PreCompress",
+  SessionEnd: "SessionEnd",
+});
+
+export async function configureGemini({
+  installationId,
+  nodePath = process.execPath,
+  runtimePath,
+  settingsPath = join(homedir(), ".gemini", "settings.json"),
+}) {
+  validateInputs({ installationId, runtimePath });
+  const settings = await readJson(settingsPath, {});
+  settings.hooks = settings.hooks && typeof settings.hooks === "object" ? settings.hooks : {};
+  for (const [hostEvent, runtimeEvent] of Object.entries(GEMINI_HOOKS)) {
+    const current = Array.isArray(settings.hooks[hostEvent]) ? settings.hooks[hostEvent] : [];
+    const unrelated = current.filter((entry) => !Array.isArray(entry?.hooks) || !entry.hooks.some(isManaged));
+    settings.hooks[hostEvent] = [...unrelated, {
+      sequential: true,
+      hooks: [{
+        type: "command",
+        name: "Halofy lifecycle",
+        command: managedCommand(nodePath, runtimePath, runtimeEvent, installationId),
+        timeout: 20_000,
+      }],
+    }];
+  }
+  settings.mcpServers = settings.mcpServers && typeof settings.mcpServers === "object" ? settings.mcpServers : {};
+  const replacedLegacyMcpEntries = replaceHalofyMcpEntries(
+    settings.mcpServers,
+    managedMcp(nodePath, runtimePath, installationId),
+  );
+  await writePrivateFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+  return { configuredPaths: [settingsPath], hookEvents: Object.keys(GEMINI_HOOKS), replacedLegacyMcpEntries };
+}
+
+const VSCODE_HOOKS = Object.freeze({
+  SessionStart: "SessionStart",
+  UserPromptSubmit: "UserPromptSubmit",
+  PostToolUse: "PostToolUse",
+  PreCompact: "PreCompact",
+  Stop: "Stop",
+  SubagentStart: "SubagentStart",
+  SubagentStop: "SubagentStop",
+});
+
+export async function configureVscode({
+  projectRoot,
+  installationId,
+  nodePath = process.execPath,
+  runtimePath,
+  hooksPath = join(homedir(), ".copilot", "hooks", "halofy.json"),
+}) {
+  validateInputs({ installationId, runtimePath });
+  const hooks = await readJson(hooksPath, {});
+  mergeFlatHooks(hooks, VSCODE_HOOKS, (eventName) => ({
+    type: "command",
+    command: managedCommand(nodePath, runtimePath, eventName, installationId),
+    timeout: 20,
+  }));
+  const mcpPath = join(resolve(projectRoot), ".vscode", "mcp.json");
+  const mcp = await readJson(mcpPath, {});
+  mcp.servers = mcp.servers && typeof mcp.servers === "object" ? mcp.servers : {};
+  const replacedLegacyMcpEntries = replaceHalofyMcpEntries(
+    mcp.servers,
+    managedMcp(nodePath, runtimePath, installationId, { explicitType: true }),
+  );
+  await writePrivateFile(hooksPath, `${JSON.stringify(hooks, null, 2)}\n`);
+  await writePrivateFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
+  return { configuredPaths: [hooksPath, mcpPath], hookEvents: Object.keys(VSCODE_HOOKS), replacedLegacyMcpEntries };
+}
+
+const CODEX_HOOKS = Object.freeze({
+  SessionStart: "SessionStart",
+  UserPromptSubmit: "UserPromptSubmit",
+  PostToolUse: "PostToolUse",
+  PreCompact: "PreCompact",
+  Stop: "Stop",
+  SubagentStart: "SubagentStart",
+  SubagentStop: "SubagentStop",
+});
+
+function replaceTomlSection(source, heading, replacement) {
+  const lines = String(source || "").split(/\r?\n/);
+  const start = lines.findIndex((line) => line.trim() === `[${heading}]`);
+  if (start !== -1) {
+    let end = start + 1;
+    while (end < lines.length && !/^\s*\[[^\]]+\]\s*$/.test(lines[end])) end += 1;
+    lines.splice(start, end - start);
+  }
+  const body = lines.join("\n").trimEnd();
+  return `${body ? `${body}\n\n` : ""}${replacement}\n`;
+}
+
+function removeTomlSection(source, heading) {
+  const lines = String(source || "").split(/\r?\n/);
+  const start = lines.findIndex((line) => line.trim() === `[${heading}]`);
+  if (start === -1) return { source: String(source || ""), removed: false, legacy: false };
+  let end = start + 1;
+  while (end < lines.length && !/^\s*\[[^\]]+\]\s*$/.test(lines[end])) end += 1;
+  const section = lines.slice(start, end).join("\n");
+  lines.splice(start, end - start);
+  return {
+    source: `${lines.join("\n").trimEnd()}\n`,
+    removed: true,
+    legacy: !/halofy-agent\.mjs|--connection/.test(section),
+  };
+}
+
+function enableTomlFeature(source, name) {
+  const lines = String(source || "").split(/\r?\n/);
+  const start = lines.findIndex((line) => line.trim() === "[features]");
+  if (start === -1) return `${String(source || "").trimEnd()}${String(source || "").trim() ? "\n\n" : ""}[features]\n${name} = true\n`;
+  let end = start + 1;
+  while (end < lines.length && !/^\s*\[[^\]]+\]\s*$/.test(lines[end])) end += 1;
+  const key = new RegExp(`^\\s*${name}\\s*=`);
+  const existing = lines.slice(start + 1, end).findIndex((line) => key.test(line));
+  if (existing === -1) lines.splice(end, 0, `${name} = true`);
+  else lines[start + 1 + existing] = `${name} = true`;
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+export async function configureCodex({
+  installationId,
+  nodePath = process.execPath,
+  runtimePath,
+  codexRoot = process.env.CODEX_HOME || join(homedir(), ".codex"),
+}) {
+  validateInputs({ installationId, runtimePath });
+  const hooksPath = join(codexRoot, "hooks.json");
+  const hooks = await readJson(hooksPath, {});
+  mergeFlatHooks(hooks, CODEX_HOOKS, (eventName) => ({
+    hooks: [{ type: "command", command: managedCommand(nodePath, runtimePath, eventName, installationId), timeout: 20 }],
+  }));
+  const configPath = join(codexRoot, "config.toml");
+  let source = "";
+  try { source = await readFile(configPath, "utf8"); } catch (error) { if (error?.code !== "ENOENT") throw error; }
+  const section = [
+    "[mcp_servers.halofy]",
+    `command = ${JSON.stringify(resolve(nodePath))}`,
+    `args = ${JSON.stringify([resolve(runtimePath), "mcp", "--connection", installationId])}`,
+  ].join("\n");
+  await writePrivateFile(hooksPath, `${JSON.stringify(hooks, null, 2)}\n`);
+  const withoutHalomem = removeTomlSection(source, "mcp_servers.halomem");
+  const withoutHalofy = removeTomlSection(withoutHalomem.source, "mcp_servers.halofy");
+  const withMcp = replaceTomlSection(withoutHalofy.source, "mcp_servers.halofy", section);
+  await writePrivateFile(configPath, enableTomlFeature(withMcp, "hooks"));
+  return {
+    configuredPaths: [hooksPath, configPath],
+    hookEvents: Object.keys(CODEX_HOOKS),
+    replacedLegacyMcpEntries: Number(withoutHalomem.legacy) + Number(withoutHalofy.legacy),
+  };
+}
+
+const CLINE_HOOKS = Object.freeze({
+  TaskStart: "TaskStart",
+  UserPromptSubmit: "UserPromptSubmit",
+  PostToolUse: "PostToolUse",
+  TaskCancel: "TaskCancel",
+});
+
+export async function configureCline({
+  installationId,
+  nodePath = process.execPath,
+  runtimePath,
+  clineRoot = join(homedir(), "Documents", "Cline"),
+}) {
+  validateInputs({ installationId, runtimePath });
+  const hooksRoot = join(clineRoot, "Hooks");
+  await ensurePrivateDirectory(hooksRoot);
+  const configuredPaths = [];
+  for (const [hostEvent, runtimeEvent] of Object.entries(CLINE_HOOKS)) {
+    const path = join(hooksRoot, hostEvent);
+    const command = managedCommand(nodePath, runtimePath, runtimeEvent, installationId);
+    await writePrivateFile(path, `#!/usr/bin/env sh\nexec ${command}\n`);
+    if (process.platform !== "win32") await chmod(path, 0o700);
+    configuredPaths.push(path);
+  }
+  const mcpPath = join(clineRoot, "MCP", "cline_mcp_settings.json");
+  const mcp = await readJson(mcpPath, {});
+  mcp.mcpServers = mcp.mcpServers && typeof mcp.mcpServers === "object" ? mcp.mcpServers : {};
+  const replacedLegacyMcpEntries = replaceHalofyMcpEntries(
+    mcp.mcpServers,
+    managedMcp(nodePath, runtimePath, installationId),
+  );
+  await writePrivateFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
+  configuredPaths.push(mcpPath);
+  return { configuredPaths, hookEvents: Object.keys(CLINE_HOOKS), replacedLegacyMcpEntries };
+}

package/src/host-hook.mjs

@@ -0,0 +1,188 @@
+import { createHash } from "node:crypto";
+import { basename } from "node:path";
+import { LifecycleRuntime } from "./runtime.mjs";
+import { normalizeClaudeHookEvent, normalizeHostMessageEvent } from "./session.mjs";
+import { defaultRuntimeDirectory } from "./storage.mjs";
+import { readHookInput } from "./claude-hook.mjs";
+
+const USER_EVENTS = new Set(["UserPromptSubmit", "beforeSubmitPrompt", "BeforeAgent", "pre_llm_call"]);
+const ASSISTANT_EVENTS = new Set(["afterAgentResponse", "AfterAgent", "post_llm_call", "transform_llm_output"]);
+const TOOL_EVENTS = new Set(["PostToolUse", "PostToolUseFailure", "postToolUse", "postToolUseFailure", "AfterTool", "post_tool_call", "after_tool_call"]);
+const START_EVENTS = new Set(["SessionStart", "sessionStart", "TaskStart", "on_session_start", "session_start"]);
+const END_EVENTS = new Set(["SessionEnd", "sessionEnd", "on_session_finalize", "session_end"]);
+const STOP_EVENTS = new Set(["Stop", "stop", "TaskCancel", "on_session_end", "agent_end"]);
+const COMPACT_EVENTS = new Set(["PreCompact", "preCompact", "PreCompress", "before_compaction"]);
+const SUBAGENT_START_EVENTS = new Set(["SubagentStart", "subagentStart", "subagent_start", "subagent_spawned"]);
+const SUBAGENT_STOP_EVENTS = new Set(["SubagentStop", "subagentStop", "subagent_stop", "subagent_ended"]);
+
+export const HOST_HOOK_EVENTS = Object.freeze(new Set([
+  ...USER_EVENTS, ...ASSISTANT_EVENTS, ...TOOL_EVENTS, ...START_EVENTS,
+  ...END_EVENTS, ...STOP_EVENTS, ...COMPACT_EVENTS,
+  ...SUBAGENT_START_EVENTS, ...SUBAGENT_STOP_EVENTS,
+]));
+
+function digest(value) {
+  return createHash("sha256").update(String(value)).digest("hex");
+}
+
+function hostSession(input) {
+  return String(input.session_id || input.conversation_id || input.taskId || input.task_id ||
+    input.sessionKey || input.session_key || input.extra?.session_id || "");
+}
+
+function childSession(input, parent) {
+  const child = input.agent_id || input.subagent_id || input.child_subagent_id ||
+    input.childSessionKey || input.child_session_id || input.extra?.child_session_id;
+  return child ? `${parent}:subagent:${String(child)}` : parent;
+}
+
+function eventEvidenceId(eventName, input) {
+  const native = input.event_id || input.generation_id || input.turn_id || input.tool_call_id ||
+    input.taskId || input.task_id || input.extra?.turn_id || input.extra?.tool_call_id;
+  return native ? `${eventName}:${String(native)}` : `${eventName}:${digest(JSON.stringify(input))}`;
+}
+
+function promptText(input) {
+  return input.prompt ?? input.user_prompt ?? input.user_message ??
+    input.userPromptSubmit?.prompt ?? input.extra?.user_message;
+}
+
+function assistantText(input) {
+  return input.text ?? input.prompt_response ?? input.assistant_response ?? input.response_text ??
+    input.extra?.assistant_response ?? input.extra?.response_text;
+}
+
+function toolInput(input) {
+  return input.tool_input ?? input.parameters ?? input.preToolUse?.parameters ?? input.postToolUse?.parameters ??
+    input.extra?.args ?? input.args;
+}
+
+function toolOutput(input) {
+  return input.tool_response ?? input.tool_output ?? input.tool_result ?? input.result ?? input.postToolUse?.result ??
+    input.extra?.result ?? input.extra?.error_message;
+}
+
+function recallBlocks(result) {
+  const blocks = Array.isArray(result?.blocks) ? result.blocks : Array.isArray(result) ? result : [];
+  return blocks.filter((block) => block && typeof block.recallRef === "string" &&
+    typeof block.content === "string" && block.content.trim()).slice(0, 12).map((block, rank) => ({
+      rank: rank + 1,
+      recallRef: block.recallRef.slice(0, 256),
+      content: block.content.trim(),
+    }));
+}
+
+function recallOutput(clientKind, eventName, result) {
+  const rankedBlocks = recallBlocks(result);
+  if (rankedBlocks.length === 0) return null;
+  const additionalContext = `<<<HALOFY_CONTEXT_BLOCKS_V1>>>\n${JSON.stringify({ rankedBlocks })}\n<<<END_HALOFY_CONTEXT_BLOCKS_V1>>>`;
+  if (clientKind === "cursor") {
+    return START_EVENTS.has(eventName) ? JSON.stringify({ additional_context: additionalContext }) : null;
+  }
+  if (clientKind === "cline") return JSON.stringify({ cancel: false, contextModification: additionalContext });
+  if (clientKind === "hermes-agents") return JSON.stringify({ context: additionalContext });
+  return JSON.stringify({ hookSpecificOutput: { hookEventName: eventName, additionalContext } });
+}
+
+async function within(milliseconds, action) {
+  let timer;
+  try {
+    return await Promise.race([
+      action(),
+      new Promise((resolve) => { timer = setTimeout(() => resolve(null), milliseconds); }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+async function enqueueMessage(runtime, connection, session, role, text, eventName, input) {
+  if (typeof text !== "string") return;
+  await runtime.enqueueSequencedEvents(session, ({ nextSequence }) => [normalizeHostMessageEvent({
+    clientKind: connection.clientKind, role, text,
+    eventId: eventEvidenceId(eventName, input),
+    occurredAt: input.timestamp || new Date().toISOString(),
+  }, { sequence: nextSequence })]);
+}
+
+async function enqueueTool(runtime, session, eventName, input) {
+  const failed = /failure/i.test(eventName) || Boolean(input.error || input.extra?.error_message || input.postToolUse?.success === false);
+  const common = {
+    event_id: eventEvidenceId(eventName, input),
+    tool_name: input.tool_name ?? input.toolName ?? input.postToolUse?.toolName ?? input.extra?.tool_name,
+    tool_use_id: input.tool_use_id ?? input.tool_call_id ?? input.extra?.tool_call_id,
+    tool_input: toolInput(input),
+    tool_response: toolOutput(input),
+    ...(failed ? { tool_error: input.error || input.extra?.error_message || true } : {}),
+  };
+  await runtime.enqueueSequencedEvents(session, ({ sessionHash, nextSequence }) => [
+    normalizeClaudeHookEvent("tool_call", common, { sessionHash, sequence: nextSequence }),
+    normalizeClaudeHookEvent("tool_result", common, { sessionHash, sequence: nextSequence + 1 }),
+  ]);
+}
+
+/** Runs one reviewed host hook without blocking the host when Halofy browns out. */
+export async function runHostLifecycleHook(connection, eventName, {
+  input,
+  root = defaultRuntimeDirectory(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+  runtimeFactory = (activeConnection, options) => new LifecycleRuntime(activeConnection, options),
+} = {}) {
+  try {
+    if (!HOST_HOOK_EVENTS.has(eventName)) throw new Error("unsupported host lifecycle hook");
+    const hookInput = input ?? await readHookInput();
+    const session = hostSession(hookInput);
+    if (!session) return { handled: true, unavailable: "missing_host_session" };
+    const runtime = runtimeFactory(connection, { root });
+
+    if (START_EVENTS.has(eventName)) {
+      await runtime.replay();
+      await runtime.heartbeat(connection.capabilities || {});
+      const project = hookInput.cwd ? basename(String(hookInput.cwd)) : "";
+      const recalled = await runtime.recall(session,
+        `${project ? `${project} ` : ""}project policy, conventions, decisions, preferences, and known context`);
+      const output = recallOutput(connection.clientKind, eventName, recalled);
+      if (output) stdout.write(output);
+    } else if (USER_EVENTS.has(eventName)) {
+      const prompt = promptText(hookInput);
+      await enqueueMessage(runtime, connection, session, "user", prompt, eventName, hookInput);
+      if (connection.clientKind !== "cursor" && typeof prompt === "string" && prompt.trim()) {
+        const recalled = await runtime.recall(session, prompt.slice(0, 8_000));
+        const output = recallOutput(connection.clientKind, eventName, recalled);
+        if (output) stdout.write(output);
+      }
+    } else if (ASSISTANT_EVENTS.has(eventName)) {
+      await enqueueMessage(runtime, connection, session, "assistant", assistantText(hookInput), eventName, hookInput);
+      await runtime.commitIfThreshold(session);
+    } else if (TOOL_EVENTS.has(eventName)) {
+      await enqueueTool(runtime, session, eventName, hookInput);
+    } else if (COMPACT_EVENTS.has(eventName)) {
+      await runtime.enqueueSequencedEvents(session, ({ sessionHash, nextSequence }) => [
+        normalizeClaudeHookEvent("compaction", {
+          ...hookInput,
+          event_id: eventEvidenceId(eventName, hookInput),
+        }, { sessionHash, sequence: nextSequence }),
+      ]);
+      await runtime.commit(session, "pre_compaction");
+    } else if (SUBAGENT_START_EVENTS.has(eventName)) {
+      await runtime.resolveSession(childSession(hookInput, session), session);
+    } else if (SUBAGENT_STOP_EVENTS.has(eventName)) {
+      await within(10_000, () => runtime.close(childSession(hookInput, session), "session_end"));
+    } else if (END_EVENTS.has(eventName)) {
+      await within(15_000, () => runtime.close(session));
+    } else if (STOP_EVENTS.has(eventName)) {
+      if (connection.clientKind === "vscode" || connection.clientKind === "cline") {
+        await within(15_000, () => runtime.close(session));
+      } else {
+        await runtime.commitIfThreshold(session);
+      }
+    }
+    return { handled: true };
+  } catch (error) {
+    const code = error && typeof error === "object" && typeof error.code === "string"
+      ? error.code : "runtime_unavailable";
+    stderr.write(`[halofy] lifecycle hook degraded: ${code}\n`);
+    return { handled: true, degraded: true };
+  }
+}

package/src/install.mjs

@@ -6,33 +6,9 @@ import { generateInstallationKeyPair } from "./crypto.mjs";
 import { ConnectionStore, defaultRuntimeDirectory, ensurePrivateDirectory, readJson, writePrivateFile } from "./storage.mjs";
 import { SignedRuntimeTransport } from "./transport.mjs";
 import { INSTALLER_VERSION, RUNTIME_VERSION } from "./version.mjs";
+import { CLIENT_KINDS, CLIENT_REGISTRY, lifecycleClient } from "./client-registry.mjs";
 
-export const CLAUDE_CAPABILITIES = Object.freeze({
-  sessionStart: true,
-  userPromptSubmit: true,
-  stop: true,
-  preCompact: true,
-  sessionEnd: true,
-  subagentStart: true,
-  subagentStop: true,
-  postToolUse: true,
-  postToolUseFailure: true,
-  postToolBatch: true,
-  conversationArchive: true,
-  archiveProtocolV1: true,
-  userMessages: true,
-  assistantMessages: true,
-  toolInputs: true,
-  toolOutputs: true,
-  toolFailures: true,
-  images: false,
-  contextUseEvidence: false,
-  artifactBodies: false,
-  artifactReferences: true,
-  subagents: true,
-  compactionCheckpoints: true,
-  contextRecalled: true,
-});
+export const CLAUDE_CAPABILITIES = CLIENT_REGISTRY["claude-code"].capabilities;
 
 export async function consumeInstallationClaim({
   serverUrl,
@@ -43,7 +19,7 @@ export async function consumeInstallationClaim({
   proofStorage,
   installerVersion = INSTALLER_VERSION,
   pluginVersion = RUNTIME_VERSION,
-  capabilities = CLAUDE_CAPABILITIES,
+  capabilities = lifecycleClient(clientKind).capabilities,
   fetchImpl = globalThis.fetch,
 }) {
   const response = await fetchImpl(`${serverUrl}/v1/agent-installations/claim`, {
@@ -73,7 +49,8 @@ export async function installLocalConnection({
   fetchImpl = globalThis.fetch,
   sendHeartbeat = true,
 }) {
-  if (clientKind !== "claude-code") throw new Error("only the local Claude Code adapter is available");
+  if (!CLIENT_KINDS.includes(clientKind)) throw new Error("the selected lifecycle adapter is not packaged");
+  const client = lifecycleClient(clientKind);
   const normalizedServer = new URL(serverUrl);
   if (normalizedServer.protocol !== "https:" && normalizedServer.hostname !== "localhost" && normalizedServer.hostname !== "127.0.0.1") {
     throw new Error("installation claims require HTTPS (localhost is allowed for development)");
@@ -113,7 +90,7 @@ export async function installLocalConnection({
     publicJwk: keyPair.publicJwk,
     privateJwk: keyPair.privateJwk,
     keyThumbprint: keyPair.thumbprint,
-    capabilities: CLAUDE_CAPABILITIES,
+    capabilities: client.capabilities,
     installerVersion: INSTALLER_VERSION,
     pluginVersion: RUNTIME_VERSION,
     proofStorage,
@@ -132,7 +109,7 @@ export async function installLocalConnection({
   let heartbeat = false;
   if (sendHeartbeat) {
     try {
-      await new SignedRuntimeTransport(connection, { fetchImpl }).heartbeat(CLAUDE_CAPABILITIES, {
+      await new SignedRuntimeTransport(connection, { fetchImpl }).heartbeat(client.capabilities, {
         pluginVersion: RUNTIME_VERSION,
         proofStorage,
         diagnostics: { queueDepth: 0, oldestPendingAt: null, expiredCount: 0 },

package/src/installer-cli.mjs

@@ -1,6 +1,8 @@
 import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
-import { resolve } from "node:path";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
 import {
   heartbeatInstalledConnection,
   installLocalConnection,
@@ -8,6 +10,8 @@ import {
   localMcpSnippet,
 } from "./install.mjs";
 import { configureClaudeProject } from "./claude-config.mjs";
+import { configureCline, configureCodex, configureCursor, configureGemini, configureVscode } from "./host-config.mjs";
+import { CLIENT_KINDS, lifecycleClient } from "./client-registry.mjs";
 import { defaultRuntimeDirectory } from "./storage.mjs";
 import { DISCLOSURE_VERSION, INSTALLER_VERSION } from "./version.mjs";
 
@@ -27,9 +31,9 @@ export function parseInstallerArgs(argv) {
   }
   const serverUrl = values.get("--server");
   const claim = values.get("--claim");
-  if (command !== "install" || clientKind !== "claude-code" || !serverUrl || !claim ||
+  if (command !== "install" || !CLIENT_KINDS.includes(clientKind) || !serverUrl || !claim ||
       !/^hsc_[A-Za-z0-9_-]{43}$/.test(claim)) {
-    throw new Error("Usage: agent-connect install claude-code --server <https-url> --claim <one-use-claim>");
+    throw new Error("Usage: agent-connect install <supported-client> --server <https-url> --claim <one-use-claim>");
   }
   return {
     clientKind,
@@ -51,22 +55,68 @@ export function detectClaudeCode() {
   return version || "detected";
 }
 
-export function disclosureText({ serverUrl, projectRoot, claudeVersion }) {
+export function detectCline(home = homedir()) {
+  if (existsSync(join(home, "Documents", "Cline"))) return "detected";
+  for (const root of [join(home, ".vscode", "extensions"), join(home, ".cursor", "extensions")]) {
+    try {
+      if (readdirSync(root).some((name) => name.startsWith("saoudrizwan.claude-dev-"))) return "detected";
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+  }
+  throw new Error("Cline was not found in VS Code, Cursor, or ~/Documents/Cline");
+}
+
+export function detectClient(clientKind) {
+  const client = lifecycleClient(clientKind);
+  if (clientKind === "cline") return detectCline();
+  if (!client.command) throw new Error(`${client.label} does not have a packaged detector`);
+  const result = spawnSync(client.command, ["--version"], {
+    encoding: "utf8",
+    shell: false,
+    timeout: 10_000,
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0) throw new Error(`${client.label} was not found on PATH`);
+  return String(result.stdout || result.stderr || "").trim().slice(0, 128) || "detected";
+}
+
+export function disclosureText({ serverUrl, projectRoot, clientKind, clientVersion }) {
+  const client = lifecycleClient(clientKind);
+  const observedCategories = [
+    ["user messages", client.capabilities.userMessages],
+    ["assistant messages", client.capabilities.assistantMessages],
+    ["tool inputs", client.capabilities.toolInputs],
+    ["tool outputs", client.capabilities.toolOutputs],
+    ["tool failures", client.capabilities.toolFailures],
+    ["images", client.capabilities.images],
+    ["artifact bodies", client.capabilities.artifactBodies],
+    ["artifact references", client.capabilities.artifactReferences],
+    ["subagents", client.capabilities.subagents],
+    ["compaction checkpoints", client.capabilities.compactionCheckpoints],
+    ["context-use evidence", client.capabilities.contextUseEvidence],
+  ];
+  const supported = observedCategories.filter(([, value]) => value === true).map(([name]) => name);
+  const unsupported = observedCategories.filter(([, value]) => value !== true).map(([name]) => name);
   return [
-    "Halofy Claude Code lifecycle connection",
+    `Halofy ${client.label} lifecycle connection`,
     `Installer: @halofy/agent-connect@${INSTALLER_VERSION}`,
     `Server: ${new URL(serverUrl).origin}`,
-    `Claude Code: ${claudeVersion}`,
+    `${client.label}: ${clientVersion}`,
     `Project: ${projectRoot}`,
     "",
-    "This single installation replaces an existing Halofy bearer MCP entry in this project and enables:",
+    "This single installation replaces an existing Halofy bearer MCP entry where supported and enables:",
     "- governed memory tools and recall",
-    "- prompts and assistant responses exposed by Claude's transcript hooks,",
-    "- supported tool inputs/results/failures, subagents, compaction, and session end,",
+    `- conversation events exposed by ${client.label}'s reviewed hooks,`,
+    "- explicitly supported tool, subagent, compaction, and close evidence,",
     "- encrypted local retry queue and governed retained conversations, and",
     "- canonical learning when the selected badge permits writes.",
     "",
-    "Images and artifact bodies are recorded as explicit unsupported placeholders; coverage may be Partial.",
+    `Supported capture categories: ${supported.length > 0 ? supported.join(", ") : "none"}.`,
+    `Unsupported capture categories: ${unsupported.length > 0 ? unsupported.join(", ") : "none"}.`,
+    client.coverage === "complete"
+      ? "This reviewed host surface can report complete coverage when all declared evidence is observed."
+      : `This host has partial coverage (${client.reason}); missing categories remain explicit.`,
     "Authorized organization managers may review retained conversations and summaries.",
     "This does not scan historical files, other applications, clipboard, keystrokes, or other agents.",
     "Disconnecting stops future capture but does not erase retained data.",
@@ -90,14 +140,15 @@ export async function runInstaller(argv, {
   root = defaultRuntimeDirectory(),
   output = process.stdout,
   detectClaude = detectClaudeCode,
+  detectHost = detectClient,
   confirm = confirmDisclosure,
   fetchImpl = globalThis.fetch,
   sourceRoot,
   claudeConfigPath,
 } = {}) {
   const input = parseInstallerArgs(argv);
-  const claudeVersion = await detectClaude();
-  output.write(`${disclosureText({ ...input, claudeVersion })}\n`);
+  const clientVersion = input.clientKind === "claude-code" ? await detectClaude() : await detectHost(input.clientKind);
+  output.write(`${disclosureText({ ...input, clientVersion })}\n`);
   await confirm();
 
   const installed = await installLocalConnection({
@@ -109,13 +160,25 @@ export async function runInstaller(argv, {
     sendHeartbeat: false,
   });
   const bundle = await installRuntimeBundle({ root, ...(sourceRoot ? { sourceRoot } : {}) });
-  const configured = await configureClaudeProject({
+  const common = {
     projectRoot: input.projectRoot,
     installationId: installed.installationId,
     serverUrl: input.serverUrl,
     runtimePath: bundle.runtimePath,
-    ...(claudeConfigPath ? { claudeConfigPath } : {}),
-  });
+  };
+  const configured = input.clientKind === "claude-code"
+    ? await configureClaudeProject({ ...common, ...(claudeConfigPath ? { claudeConfigPath } : {}) })
+    : input.clientKind === "cursor"
+      ? await configureCursor(common)
+      : input.clientKind === "gemini-cli"
+        ? await configureGemini(common)
+        : input.clientKind === "vscode"
+          ? await configureVscode(common)
+          : input.clientKind === "codex"
+            ? await configureCodex(common)
+            : input.clientKind === "cline"
+              ? await configureCline(common)
+              : (() => { throw new Error("the selected adapter is not packaged yet"); })();
   let heartbeat = false;
   try {
     heartbeat = await heartbeatInstalledConnection({
@@ -133,12 +196,12 @@ export async function runInstaller(argv, {
     installerVersion: INSTALLER_VERSION,
     publishedPackage: true,
     projectConfigured: true,
-    configuredPaths: [configured.mcpPath, configured.settingsPath],
-    replacedLegacyMcpEntries: configured.replacedLegacyMcpEntries,
+    configuredPaths: configured.configuredPaths || [configured.mcpPath, configured.settingsPath],
+    replacedLegacyMcpEntries: configured.replacedLegacyMcpEntries || 0,
     mcpConfiguration: localMcpSnippet({
       proxyPath: bundle.runtimePath,
       installationId: installed.installationId,
     }),
-    nextStep: "Restart Claude Code in this project, then check the connection in Halofy.",
+    nextStep: `Restart ${lifecycleClient(input.clientKind).label}, then check the connection in Halofy.`,
   };
 }

package/src/runtime.mjs

@@ -132,22 +132,39 @@ export class LifecycleRuntime {
   }
 
   async enqueueEvents(hostSessionId, events) {
+    const sessionHash = this.sessionHash(hostSessionId);
+    await withFileLock(this.operationLockPath, async () => {
+      await this.#enqueueEventsUnlocked(sessionHash, events);
+    });
+    return this.replay();
+  }
+
+  async enqueueSequencedEvents(hostSessionId, factory) {
     const sessionHash = this.sessionHash(hostSessionId);
     await withFileLock(this.operationLockPath, async () => {
       const cursor = await this.cursors.get(sessionHash);
-      const recentEventKeys = new Set(Array.isArray(cursor.recentEventKeys) ? cursor.recentEventKeys : []);
-      const unseenEvents = events.filter((event) => !recentEventKeys.has(event.eventKey));
-      if (unseenEvents.length === 0) return;
-      await this.queue.enqueueSessionEvents(sessionHash, unseenEvents, {
-        maxBatchEvents: this.maxBatchEvents,
-        maxBatchBytes: this.maxBatchBytes,
-        acknowledgedSequence: cursor.sequence,
-      });
-      await this.cursors.rememberEventKeys(sessionHash, unseenEvents.map((event) => event.eventKey));
+      const events = factory({ sessionHash, nextSequence: cursor.sequence + 1 });
+      if (!Array.isArray(events) || events.length < 1 || events.length > this.maxBatchEvents) {
+        throw new Error("sequenced host event batch is invalid");
+      }
+      await this.#enqueueEventsUnlocked(sessionHash, events, cursor);
     });
     return this.replay();
   }
 
+  async #enqueueEventsUnlocked(sessionHash, events, knownCursor) {
+    const cursor = knownCursor || await this.cursors.get(sessionHash);
+    const recentEventKeys = new Set(Array.isArray(cursor.recentEventKeys) ? cursor.recentEventKeys : []);
+    const unseenEvents = events.filter((event) => !recentEventKeys.has(event.eventKey));
+    if (unseenEvents.length === 0) return;
+    await this.queue.enqueueSessionEvents(sessionHash, unseenEvents, {
+      maxBatchEvents: this.maxBatchEvents,
+      maxBatchBytes: this.maxBatchBytes,
+      acknowledgedSequence: cursor.sequence,
+    });
+    await this.cursors.rememberEventKeys(sessionHash, unseenEvents.map((event) => event.eventKey));
+  }
+
   async replay() {
     return withFileLock(this.operationLockPath, () => this.#replayUnlocked());
   }

package/src/session.mjs

@@ -387,6 +387,37 @@ export function normalizeClaudeHookEvent(type, input, { sessionHash, sequence })
   return { ...event, sequence };
 }
 
+/** Normalize text exposed directly by a reviewed non-Claude host hook. */
+export function normalizeHostMessageEvent({
+  clientKind,
+  role,
+  text,
+  eventId,
+  occurredAt = new Date().toISOString(),
+}, { sequence }) {
+  if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(String(clientKind)) ||
+      !["user", "assistant", "system"].includes(String(role)) ||
+      typeof text !== "string" || !eventId) {
+    throw new Error("host message evidence is incomplete");
+  }
+  const payload = boundedCompletePayload({
+    role,
+    contentFormat: "utf8",
+    captureStatus: "complete",
+    text,
+  }, { role, body: text, format: "utf8" });
+  const stableId = digest(`${clientKind}\0${String(eventId)}`);
+  return {
+    ...normalizedEvent({
+      eventKey: `${clientKind}:message:${stableId}`,
+      type: "message",
+      occurredAt,
+      payload,
+    }),
+    sequence,
+  };
+}
+
 export async function readClaudeTranscriptSuffix(path, cursor, sessionHash) {
   const bytes = await readFile(path);
   const start = Number.isSafeInteger(cursor?.byteOffset) && cursor.byteOffset <= bytes.length ? cursor.byteOffset : 0;

package/src/version.mjs

@@ -1,4 +1,4 @@
 export const PACKAGE_NAME = "@halofy/agent-connect";
-export const INSTALLER_VERSION = "0.1.0";
-export const RUNTIME_VERSION = "0.1.0";
-export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-08-28";
+export const INSTALLER_VERSION = "0.2.0";
+export const RUNTIME_VERSION = "0.2.0";
+export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-08-29";