@halofy/agent-connect 0.5.0 → 0.5.1

package/README.md

@@ -16,10 +16,16 @@ agent connections:
 - a stdio-to-signed-Streamable-HTTP MCP proof proxy; and
 - one local claim consumer and proof runtime shared by every packaged adapter.
 
+Hook-driven recall injection is disabled in this release
+(`RECALL_INJECTION_ENABLED` in `src/session.mjs`): the runtime captures
+conversations and serves the agent-invoked MCP memory tools, but does not push
+recalled memory into host sessions on session start or prompt submit. The
+bounded recall block formats stay in place and tested for when it returns.
+
 There is one setup path for every packaged client:
 
 ```bash
-npx --yes @halofy/agent-connect@0.5.0 install <client-kind> \
+npx --yes @halofy/agent-connect@0.5.1 install <client-kind> \
   --server https://app.halofy.ai \
   --claim '<one-time-claim>'
 ```
@@ -44,7 +50,10 @@ to conversation-capture evidence by its name.
 
 Run the server-returned command in the operating-system terminal from the
 computer where the selected client runs, never in agent chat. The installer displays
-the capture disclosure, requires the recipient to type `CONNECT`, generates
+the capture disclosure — including the organization the claim binds to, fetched
+from the named server so a spoofed `--server` is recognizable before
+confirmation (`unverified` when the server cannot identify the claim) —
+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

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@halofy/agent-connect",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
-  "description": "Signed Halofy lifecycle installer and runtime for supported agents",
+  "description": "Halofy lifecycle installer and runtime for supported agents; runtime requests are signed with a per-installation Ed25519 key",
   "bin": {
     "agent-connect": "bin/install.mjs",
     "halofy-agent": "bin/halofy-agent.mjs"

package/src/claude-config.mjs

@@ -1,6 +1,6 @@
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
-import { readJson, writePrivateFile } from "./storage.mjs";
+import { readJson, writeHostConfigFile } from "./storage.mjs";
 
 const CLAUDE_HOOKS = Object.freeze({
   SessionStart: { matcher: "startup|resume|clear|compact", timeout: 15 },
@@ -124,12 +124,12 @@ export async function configureClaudeProject({
       replacedClaudeMcpEntries += removeHalofyEntries(project.mcpServers, server.toString());
     }
     if (replacedClaudeMcpEntries > 0) {
-      await writePrivateFile(claudeConfigPath, `${JSON.stringify(claude, null, 2)}\n`);
+      await writeHostConfigFile(claudeConfigPath, `${JSON.stringify(claude, null, 2)}\n`);
     }
   }
 
-  await writePrivateFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
-  await writePrivateFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+  await writeHostConfigFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
+  await writeHostConfigFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
   return {
     mcpPath,
     settingsPath,

package/src/claude-hook.mjs

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { basename } from "node:path";
 import { LifecycleRuntime } from "./runtime.mjs";
-import { normalizeClaudeHookEvent } from "./session.mjs";
+import { normalizeClaudeHookEvent, RECALL_INJECTION_ENABLED, rankedRecallBlocks } from "./session.mjs";
 import { defaultRuntimeDirectory } from "./storage.mjs";
 
 function id(value) {
@@ -42,16 +42,7 @@ function childSession(input) {
 }
 
 function recallText(result, eventName) {
-  const blocks = Array.isArray(result?.blocks) ? result.blocks : Array.isArray(result) ? result : [];
-  const rankedBlocks = 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(),
-    }));
+  const rankedBlocks = rankedRecallBlocks(result);
   if (rankedBlocks.length === 0) return null;
   return JSON.stringify({
     hookSpecificOutput: {
@@ -95,20 +86,24 @@ export async function runClaudeLifecycleHook(connection, eventName, {
     if (eventName === "SessionStart") {
       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 = recallText(recalled, "SessionStart");
-      if (output) stdout.write(output);
-    } else if (eventName === "UserPromptSubmit") {
-      const prompt = String(hookInput.prompt || hookInput.user_prompt || "").slice(0, 8_000);
-      if (prompt.trim()) {
-        const recalled = await runtime.recall(session, prompt);
-        const output = recallText(recalled, "UserPromptSubmit");
+      if (RECALL_INJECTION_ENABLED) {
+        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 = recallText(recalled, "SessionStart");
         if (output) stdout.write(output);
       }
+    } else if (eventName === "UserPromptSubmit") {
+      if (RECALL_INJECTION_ENABLED) {
+        const prompt = String(hookInput.prompt || hookInput.user_prompt || "").slice(0, 8_000);
+        if (prompt.trim()) {
+          const recalled = await runtime.recall(session, prompt);
+          const output = recallText(recalled, "UserPromptSubmit");
+          if (output) stdout.write(output);
+        }
+      }
     } else if (eventName === "Stop") {
       if (!hookInput.stop_hook_active) {
         await catchUp(runtime, hookInput);

package/src/host-config.mjs

@@ -1,7 +1,7 @@
-import { chmod, readFile } from "node:fs/promises";
+import { chmod, mkdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
-import { ensurePrivateDirectory, readJson, writePrivateFile } from "./storage.mjs";
+import { readJson, writeHostConfigFile } from "./storage.mjs";
 
 function commandArg(value) {
   const text = String(value);
@@ -92,8 +92,8 @@ export async function configureCursor({
     mcp.mcpServers,
     managedMcp(nodePath, runtimePath, installationId),
   );
-  await writePrivateFile(hooksPath, `${JSON.stringify(hooks, null, 2)}\n`);
-  await writePrivateFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
+  await writeHostConfigFile(hooksPath, `${JSON.stringify(hooks, null, 2)}\n`);
+  await writeHostConfigFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
   return { configuredPaths: [hooksPath, mcpPath], hookEvents: Object.keys(CURSOR_HOOKS), replacedLegacyMcpEntries };
 }
 
@@ -133,7 +133,7 @@ export async function configureGemini({
     settings.mcpServers,
     managedMcp(nodePath, runtimePath, installationId),
   );
-  await writePrivateFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+  await writeHostConfigFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
   return { configuredPaths: [settingsPath], hookEvents: Object.keys(GEMINI_HOOKS), replacedLegacyMcpEntries };
 }
 
@@ -197,8 +197,8 @@ export async function configureKimi({
     mcp.mcpServers,
     managedMcp(nodePath, runtimePath, installationId),
   );
-  await writePrivateFile(configPath, replaceKimiManagedHooks(source, hookBlock));
-  await writePrivateFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
+  await writeHostConfigFile(configPath, replaceKimiManagedHooks(source, hookBlock));
+  await writeHostConfigFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
   return { configuredPaths: [configPath, mcpPath], hookEvents: Object.keys(KIMI_HOOKS), replacedLegacyMcpEntries };
 }
 
@@ -233,8 +233,8 @@ export async function configureVscode({
     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`);
+  await writeHostConfigFile(hooksPath, `${JSON.stringify(hooks, null, 2)}\n`);
+  await writeHostConfigFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
   return { configuredPaths: [hooksPath, mcpPath], hookEvents: Object.keys(VSCODE_HOOKS), replacedLegacyMcpEntries };
 }
 
@@ -308,11 +308,11 @@ export async function configureCodex({
     `command = ${JSON.stringify(resolve(nodePath))}`,
     `args = ${JSON.stringify([resolve(runtimePath), "mcp", "--connection", installationId])}`,
   ].join("\n");
-  await writePrivateFile(hooksPath, `${JSON.stringify(hooks, null, 2)}\n`);
+  await writeHostConfigFile(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"));
+  await writeHostConfigFile(configPath, enableTomlFeature(withMcp, "hooks"));
   return {
     configuredPaths: [hooksPath, configPath],
     hookEvents: Object.keys(CODEX_HOOKS),
@@ -335,12 +335,12 @@ export async function configureCline({
 }) {
   validateInputs({ installationId, runtimePath });
   const hooksRoot = join(clineRoot, "Hooks");
-  await ensurePrivateDirectory(hooksRoot);
+  await mkdir(hooksRoot, { recursive: true });
   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`);
+    await writeHostConfigFile(path, `#!/usr/bin/env sh\nexec ${command}\n`);
     if (process.platform !== "win32") await chmod(path, 0o700);
     configuredPaths.push(path);
   }
@@ -351,7 +351,7 @@ export async function configureCline({
     mcp.mcpServers,
     managedMcp(nodePath, runtimePath, installationId),
   );
-  await writePrivateFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
+  await writeHostConfigFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
   configuredPaths.push(mcpPath);
   return { configuredPaths, hookEvents: Object.keys(CLINE_HOOKS), replacedLegacyMcpEntries };
 }

package/src/host-hook.mjs

@@ -1,7 +1,12 @@
 import { createHash } from "node:crypto";
 import { basename } from "node:path";
 import { LifecycleRuntime } from "./runtime.mjs";
-import { normalizeClaudeHookEvent, normalizeHostMessageEvent } from "./session.mjs";
+import {
+  normalizeClaudeHookEvent,
+  normalizeHostMessageEvent,
+  RECALL_INJECTION_ENABLED,
+  rankedRecallBlocks,
+} from "./session.mjs";
 import { defaultRuntimeDirectory } from "./storage.mjs";
 import { readHookInput } from "./claude-hook.mjs";
 
@@ -62,18 +67,8 @@ function toolOutput(input) {
     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);
+  const rankedBlocks = rankedRecallBlocks(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") {
@@ -139,15 +134,20 @@ export async function runHostLifecycleHook(connection, eventName, {
     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);
+      if (RECALL_INJECTION_ENABLED) {
+        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)) {
+      // Prompt capture is independent of recall: non-Claude hosts have no
+      // transcript, so this enqueue is how user messages reach the archive.
       const prompt = promptText(hookInput);
       await enqueueMessage(runtime, connection, session, "user", prompt, eventName, hookInput);
-      if (connection.clientKind !== "cursor" && typeof prompt === "string" && prompt.trim()) {
+      if (RECALL_INJECTION_ENABLED && 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);

package/src/install.mjs

@@ -10,6 +10,57 @@ import { CLIENT_KINDS, CLIENT_REGISTRY, lifecycleClient } from "./client-registr
 
 export const CLAUDE_CAPABILITIES = CLIENT_REGISTRY["claude-code"].capabilities;
 
+/** HTTPS-or-loopback validation shared by every request that carries the claim. */
+export function normalizeLifecycleServerUrl(serverUrl) {
+  const normalizedServer = new URL(serverUrl);
+  if (normalizedServer.protocol !== "https:" && normalizedServer.hostname !== "localhost" &&
+      normalizedServer.hostname !== "127.0.0.1" && normalizedServer.hostname !== "[::1]") {
+    throw new Error("installation claims require HTTPS (localhost is allowed for development)");
+  }
+  normalizedServer.pathname = normalizedServer.pathname.replace(/\/+$/, "");
+  return normalizedServer.toString().replace(/\/$/, "");
+}
+
+/**
+ * Best-effort pre-consumption disclosure: which organization this claim binds
+ * to, shown before the CONNECT confirmation. An older server without the
+ * endpoint, or any failure, yields null — the installer then labels the
+ * organization unverified instead of failing. The claim is not consumed.
+ */
+export async function fetchClaimDisclosure({
+  serverUrl,
+  claim,
+  fetchImpl = globalThis.fetch,
+  timeoutMs = 5_000,
+}) {
+  try {
+    const normalizedServerUrl = normalizeLifecycleServerUrl(serverUrl);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+      response = await fetchImpl(`${normalizedServerUrl}/v1/agent-installations/claim-info`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ claim }),
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!response.ok) return null;
+    const body = await response.json();
+    // Server-supplied text is printed to a terminal: strip control characters
+    // (including ANSI escape introducers) and bound the length.
+    const organization = typeof body?.organization === "string"
+      ? body.organization.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").trim().slice(0, 100)
+      : "";
+    return organization ? { organization } : null;
+  } catch {
+    return null;
+  }
+}
+
 export async function consumeInstallationClaim({
   serverUrl,
   claim,
@@ -51,12 +102,7 @@ export async function installLocalConnection({
 }) {
   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)");
-  }
-  normalizedServer.pathname = normalizedServer.pathname.replace(/\/+$/, "");
-  const normalizedServerUrl = normalizedServer.toString().replace(/\/$/, "");
+  const normalizedServerUrl = normalizeLifecycleServerUrl(serverUrl);
   const store = new ConnectionStore(root);
   const pendingPath = join(root, `pending-${clientKind}.json`);
   const priorPending = await readJson(pendingPath);

package/src/installer-cli.mjs

@@ -4,6 +4,7 @@ import { createInterface } from "node:readline/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import {
+  fetchClaimDisclosure,
   heartbeatInstalledConnection,
   installLocalConnection,
   installRuntimeBundle,
@@ -81,7 +82,7 @@ export function detectClient(clientKind) {
   return String(result.stdout || result.stderr || "").trim().slice(0, 128) || "detected";
 }
 
-export function disclosureText({ serverUrl, projectRoot, clientKind, clientVersion }) {
+export function disclosureText({ serverUrl, projectRoot, clientKind, clientVersion, organization = null }) {
   const client = lifecycleClient(clientKind);
   const observedCategories = [
     ["user messages", client.capabilities.userMessages],
@@ -106,11 +107,14 @@ export function disclosureText({ serverUrl, projectRoot, clientKind, clientVersi
     `Halofy ${client.label} lifecycle connection`,
     `Installer: @halofy/agent-connect@${INSTALLER_VERSION}`,
     `Server: ${new URL(serverUrl).origin}`,
+    // The server named by --server identifies the organization this claim
+    // binds to, so a spoofed command is recognizable before CONNECT.
+    `Organization: ${organization || "unverified (the server did not identify this claim's organization)"}`,
     `${client.label}: ${clientVersion}`,
     `Project: ${projectRoot}`,
     "",
     "This single installation replaces an existing Halofy bearer MCP entry where supported and enables:",
-    "- governed memory tools and recall",
+    "- governed memory tools the agent invokes explicitly (no automatic recall is injected into sessions),",
     `- 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",
@@ -152,7 +156,16 @@ export async function runInstaller(argv, {
 } = {}) {
   const input = parseInstallerArgs(argv);
   const clientVersion = input.clientKind === "claude-code" ? await detectClaude() : await detectHost(input.clientKind);
-  output.write(`${disclosureText({ ...input, clientVersion })}\n`);
+  const claimDisclosure = await fetchClaimDisclosure({
+    serverUrl: input.serverUrl,
+    claim: input.claim,
+    fetchImpl,
+  });
+  output.write(`${disclosureText({
+    ...input,
+    clientVersion,
+    organization: claimDisclosure?.organization ?? null,
+  })}\n`);
   await confirm();
 
   const installed = await installLocalConnection({

package/src/session.mjs

@@ -256,6 +256,37 @@ function unsupportedBlockEvent({ nativeId, index, role, block, occurredAt, sourc
   });
 }
 
+/**
+ * Hook-driven recall injection is disabled for now: the runtime captures
+ * conversations and serves the agent-invoked MCP memory tools, but does not
+ * push recalled memory into host sessions on SessionStart/UserPromptSubmit.
+ * Flip to true to restore injection — the bounded block formats below and the
+ * per-host output shapes in the hook modules stay in place and tested.
+ */
+export const RECALL_INJECTION_ENABLED = false;
+
+export const MAX_RECALL_BLOCKS = 12;
+export const MAX_RECALL_BLOCK_CHARS = 8_000;
+
+/**
+ * Ranked recall blocks bounded on the client before they are injected into a
+ * host session. The server's token budget is the primary bound; these caps are
+ * defense in depth so poisoned or oversized memory content cannot flood the
+ * host context through a hook response.
+ */
+export function rankedRecallBlocks(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, MAX_RECALL_BLOCKS)
+    .map((block, rank) => ({
+      rank: rank + 1,
+      recallRef: block.recallRef.slice(0, 256),
+      content: block.content.trim().slice(0, MAX_RECALL_BLOCK_CHARS),
+    }));
+}
+
 export function deriveSessionHash({ installationId, clientKind, hostSessionId }) {
   if (!installationId || !clientKind || !hostSessionId) throw new Error("session identity is incomplete");
   return digest(`halofy-session-v1\0${installationId}\0${clientKind}\0${hostSessionId}`);

package/src/storage.mjs

@@ -31,6 +31,32 @@ export async function writePrivateFile(path, value) {
   if (platform() !== "win32") await chmod(path, 0o600);
 }
 
+/**
+ * Atomic write for a host application's config file. The parent directory is
+ * created if missing, but the permissions of an existing directory are never
+ * changed — a project root, $HOME, or ~/.cursor is not Halofy's to tighten.
+ * An existing file keeps its mode; a new file starts private (0600).
+ */
+export async function writeHostConfigFile(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  let mode = 0o600;
+  try {
+    mode = (await stat(path)).mode & 0o777;
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  const temporary = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+  const handle = await open(temporary, "wx", 0o600);
+  try {
+    await handle.writeFile(value);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await rename(temporary, path);
+  if (platform() !== "win32") await chmod(path, mode);
+}
+
 export async function withFileLock(path, action, { timeoutMs = 3_000, staleMs = 30_000 } = {}) {
   await ensurePrivateDirectory(dirname(path));
   const started = Date.now();

package/src/version.mjs

@@ -1,4 +1,4 @@
 export const PACKAGE_NAME = "@halofy/agent-connect";
-export const INSTALLER_VERSION = "0.5.0";
-export const RUNTIME_VERSION = "0.5.0";
-export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-08-29.2";
+export const INSTALLER_VERSION = "0.5.1";
+export const RUNTIME_VERSION = "0.5.1";
+export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-08-31.1";