@halofy/agent-connect 0.4.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.4.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.4.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: {
@@ -61,10 +52,10 @@ function recallText(result, eventName) {
   });
 }
 
-async function catchUp(runtime, input, session = hostSession(input)) {
+async function catchUp(runtime, input, session = hostSession(input), sessionFacts = {}) {
   const transcriptPath = input.agent_transcript_path || input.transcript_path;
   if (!transcriptPath || !session) return;
-  await runtime.captureClaudeTranscript(session, String(transcriptPath));
+  await runtime.captureClaudeTranscript(session, String(transcriptPath), sessionFacts);
 }
 
 async function within(milliseconds, action) {
@@ -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);
@@ -124,7 +119,9 @@ export async function runClaudeLifecycleHook(connection, eventName, {
       await runtime.commit(session, "pre_compaction");
     } else if (eventName === "SessionEnd") {
       await within(15_000, async () => {
-        await catchUp(runtime, hookInput);
+        await catchUp(runtime, hookInput, hostSession(hookInput), {
+          ...(hookInput.reason ? { closeReason: String(hookInput.reason).slice(0, 64) } : {}),
+        });
         await runtime.close(session);
       });
     } else if (eventName === "SubagentStart") {
@@ -132,7 +129,9 @@ export async function runClaudeLifecycleHook(connection, eventName, {
     } else if (eventName === "SubagentStop") {
       const child = childSession(hookInput);
       await within(10_000, async () => {
-        await catchUp(runtime, hookInput, child);
+        await catchUp(runtime, hookInput, child, {
+          ...(hookInput.agent_type ? { subagentType: String(hookInput.agent_type).slice(0, 128) } : {}),
+        });
         await runtime.close(child, "session_end");
       });
     } else if (["PostToolUse", "PostToolUseFailure"].includes(eventName)) {

package/src/client-registry.mjs

@@ -33,6 +33,10 @@ const BASE_CAPABILITIES = Object.freeze({
   subagents: false,
   compactionCheckpoints: false,
   contextRecalled: false,
+  tokenUsage: false,
+  sessionMetadata: false,
+  toolOutcomes: false,
+  thinking: false,
 });
 
 function capabilities(overrides) {
@@ -52,6 +56,12 @@ export const CLIENT_REGISTRY = Object.freeze({
       userMessages: true, assistantMessages: true, toolInputs: true,
       toolOutputs: true, toolFailures: true, artifactReferences: true,
       subagents: true, compactionCheckpoints: true, contextRecalled: true,
+      // 0.5.0: host-reported model token usage, thinking blocks, structured
+      // tool outcomes, and content-free session metadata from the native
+      // transcript. Claude Code is the only host whose reviewed adapter
+      // reads these today.
+      tokenUsage: true, sessionMetadata: true, toolOutcomes: true,
+      thinking: true,
     }),
   }),
   cursor: Object.freeze({

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],
@@ -95,6 +96,10 @@ export function disclosureText({ serverUrl, projectRoot, clientKind, clientVersi
     ["subagents", client.capabilities.subagents],
     ["compaction checkpoints", client.capabilities.compactionCheckpoints],
     ["context-use evidence", client.capabilities.contextUseEvidence],
+    ["model token usage (counts, model name, and provider request id for each reply; never prompt or reply text)", client.capabilities.tokenUsage],
+    ["thinking blocks", client.capabilities.thinking],
+    ["tool outcomes (durations, failure flags, byte sizes; file paths only as salted hashes)", client.capabilities.toolOutcomes],
+    ["host and session metadata (app version, permission mode, effort, session title; directory paths hashed unless your organization enables full device context)", client.capabilities.sessionMetadata],
   ];
   const supported = observedCategories.filter(([, value]) => value === true).map(([name]) => name);
   const unsupported = observedCategories.filter(([, value]) => value !== true).map(([name]) => name);
@@ -102,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",
@@ -148,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/runtime.mjs

@@ -1,9 +1,15 @@
 import { createHash, randomBytes } from "node:crypto";
 import { join } from "node:path";
 import { BoundedEncryptedQueue } from "./queue.mjs";
-import { CursorStore, deriveSessionHash, readClaudeTranscriptSuffix } from "./session.mjs";
+import {
+  buildClaudeMetadataPayload,
+  claudeMetadataEvent,
+  CursorStore,
+  deriveSessionHash,
+  readClaudeTranscriptSuffix,
+} from "./session.mjs";
 import { SignedRuntimeTransport } from "./transport.mjs";
-import { withFileLock } from "./storage.mjs";
+import { readJson, withFileLock, writePrivateFile } from "./storage.mjs";
 import { RUNTIME_VERSION } from "./version.mjs";
 
 export class LifecycleRuntime {
@@ -20,6 +26,7 @@ export class LifecycleRuntime {
     const connectionRoot = join(root, connection.installationId);
     this.queue = new BoundedEncryptedQueue(connectionRoot);
     this.cursors = new CursorStore(connectionRoot);
+    this.policyPath = join(connectionRoot, "policy.json");
     this.operationLockPath = join(connectionRoot, "runtime.operation.lock");
     this.maxBatchEvents = Math.min(100, Math.max(1, maxBatchEvents));
     this.maxBatchBytes = Math.min(1024 * 1024, Math.max(1024, maxBatchBytes));
@@ -99,13 +106,33 @@ export class LifecycleRuntime {
     });
   }
 
-  async captureClaudeTranscript(hostSessionId, transcriptPath) {
+  /** The server-issued capture policy from the last heartbeat (P9). */
+  async capturePolicy() {
+    const stored = await readJson(this.policyPath, { deviceContext: "hashed" });
+    return { deviceContext: stored?.deviceContext === "full" ? "full" : "hashed" };
+  }
+
+  async captureClaudeTranscript(hostSessionId, transcriptPath, sessionFacts = {}) {
     const sessionHash = this.sessionHash(hostSessionId);
+    const policy = await this.capturePolicy();
     const queued = await withFileLock(this.operationLockPath, async () => {
       const cursor = await this.cursors.get(sessionHash);
       const suffix = await readClaudeTranscriptSuffix(transcriptPath, cursor, sessionHash);
       const recentEventKeys = new Set(Array.isArray(cursor.recentEventKeys) ? cursor.recentEventKeys : []);
       const unseenEvents = suffix.events.filter((event) => !recentEventKeys.has(event.eventKey));
+      // One metadata event whenever the observed content-free session facts
+      // change. The event key hashes the payload, so an unchanged snapshot is
+      // deduplicated exactly like any repeated event.
+      const metadataPayload = buildClaudeMetadataPayload(
+        { ...suffix.metadata, ...sessionFacts },
+        { installationId: this.connection.installationId, deviceContext: policy.deviceContext },
+      );
+      if (Object.keys(metadataPayload).length > 0) {
+        const metadataEvent = claudeMetadataEvent(metadataPayload);
+        if (!recentEventKeys.has(metadataEvent.eventKey)) unseenEvents.push(metadataEvent);
+      }
+      const usageGaps = unseenEvents.filter((event) =>
+        event.type === "usage" && event.eventKey.startsWith("claude:usage-gap:")).length;
       const result = unseenEvents.length === 0
         ? { queued: 0 }
         : await this.queue.enqueueSessionEvents(sessionHash, unseenEvents, {
@@ -121,6 +148,7 @@ export class LifecycleRuntime {
         await this.cursors.update(sessionHash, { byteOffset: suffix.observedEndOffset });
       }
       await this.cursors.rememberEventKeys(sessionHash, unseenEvents.map((event) => event.eventKey));
+      if (usageGaps > 0) await this.cursors.bumpUsageGaps(usageGaps);
       return result;
     });
     if (queued.queued === 0) return { queued: 0, acknowledged: 0 };
@@ -255,15 +283,28 @@ export class LifecycleRuntime {
 
   async heartbeat(capabilities) {
     const queue = await this.queue.diagnostics();
-    return this.transport.heartbeat(capabilities, {
+    const usageGaps = await this.cursors.peekUsageGaps();
+    const response = await this.transport.heartbeat(capabilities, {
       pluginVersion: this.connection.pluginVersion || `${RUNTIME_VERSION}-local`,
       proofStorage: this.connection.proofStorage || "unknown",
       diagnostics: {
         queueDepth: queue.depth,
         oldestPendingAt: queue.oldestPendingAt,
         expiredCount: queue.expiredCount,
+        ...(usageGaps > 0 ? { usageGaps } : {}),
       },
     });
+    // The server accumulates reported gaps, so only a delivered delta is
+    // cleared — a failed heartbeat keeps the count for the next attempt.
+    if (usageGaps > 0) await this.cursors.clearUsageGaps(usageGaps);
+    // P9: persist the server-issued capture policy; the adapter consults it
+    // before SENDING device context, and the server re-checks regardless.
+    if (response && response.policy && typeof response.policy === "object") {
+      await writePrivateFile(this.policyPath, `${JSON.stringify({
+        deviceContext: response.policy.deviceContext === "full" ? "full" : "hashed",
+      })}\n`);
+    }
+    return response;
   }
 }
 

package/src/session.mjs

@@ -86,7 +86,7 @@ function boundedCompletePayload(payload, { role, body, format = "json", extra =
   });
 }
 
-function normalizedEvent({ eventKey, type, occurredAt, payload, sourceEndOffset }) {
+function normalizedEvent({ eventKey, type, occurredAt, payload, sourceEndOffset, part }) {
   const {
     role,
     contentFormat = "json",
@@ -104,6 +104,7 @@ function normalizedEvent({ eventKey, type, occurredAt, payload, sourceEndOffset
     contentFormat,
     captureStatus,
     ...(captureReasonCode ? { captureReasonCode } : {}),
+    ...(part ? { part } : {}),
     payload: wirePayload,
     payloadSha256: digest(contentFormat === "utf8" ? wirePayload : JSON.stringify(wirePayload)),
     ...(sourceEndOffset ? { sourceEndOffset } : {}),
@@ -131,19 +132,36 @@ function textEvent({ nativeId, index, role, text, occurredAt, sourceEndOffset })
   });
 }
 
-function toolEvent({ nativeId, index, type, role = "tool", toolName, toolUseId, body, occurredAt, sourceEndOffset, failed = false }) {
+const MAX_INLINE_HOST_RESULT_BYTES = 16 * 1024;
+
+/** Bounded structured host result: inline when small, digest evidence above. */
+function boundedHostResult(raw) {
+  if (raw === null || raw === undefined || typeof raw !== "object") return undefined;
+  const stableBody = stableClone(raw);
+  const bytes = bodyBytes(stableBody, "json");
+  if (bytes.length <= MAX_INLINE_HOST_RESULT_BYTES) return stableBody;
+  return { digestOnly: true, bodySha256: digest(bytes), originalBytes: bytes.length };
+}
+
+function toolEvent({ nativeId, index, type, role = "tool", toolName, toolUseId, body, occurredAt, sourceEndOffset, failed = false, hostResult, outcome }) {
   const field = type === "tool_call" ? "input" : "result";
   const stableBody = stableClone(body ?? null);
+  const boundedResult = type === "tool_result" ? boundedHostResult(hostResult) : undefined;
   const toolMetadata = {
     toolName: boundedIdentifier(toolName),
     toolUseId: boundedIdentifier(toolUseId),
     ...(type === "tool_result" ? { failed: Boolean(failed) } : {}),
+    // Content-free outcome scalars survive digest-only fallbacks so the
+    // server's plaintext tool-call row is populated even when the body is
+    // too large to retain inline.
+    ...(outcome ? { outcome } : {}),
   };
   const completePayload = {
     role,
     contentFormat: "json",
     captureStatus: "complete",
     ...toolMetadata,
+    ...(boundedResult === undefined ? {} : { hostResult: boundedResult }),
     [field]: stableBody,
   };
   const payload = containsInlineArtifactBody(stableBody)
@@ -238,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}`);
@@ -251,21 +300,182 @@ export function stripInjectedContext(value) {
   return String(value);
 }
 
+function usageInt(value) {
+  return Number.isSafeInteger(value) && value >= 0 && value < 2 ** 31 ? value : null;
+}
+
+function usageLabel(value) {
+  return typeof value === "string" && /^[\x20-\x7e]{1,128}$/.test(value) ? value : null;
+}
+
+const USAGE_MODEL_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
+
+/**
+ * One host-reported usage record per assistant message (PRD §8.1). Claude
+ * writes one JSONL line per content block of the same message, each repeating
+ * `message.usage`; the stable per-message eventKey plus keep-last suffix
+ * dedupe make that one record, never a sum of repeats (the ccusage bug).
+ * Counts come from the top-level usage totals only — `iterations[]` is the
+ * per-iteration breakdown of the same totals and is ignored.
+ */
+function usageEventFromEntry(entry, { nativeId, occurredAt, sourceEndOffset }) {
+  const message = entry.message;
+  const usage = message.usage;
+  const model = typeof message.model === "string" && USAGE_MODEL_PATTERN.test(message.model)
+    ? message.model : null;
+  const usable = model !== null && usage !== null && typeof usage === "object" &&
+    (usageInt(usage.input_tokens) !== null || usageInt(usage.output_tokens) !== null);
+  if (!usable) {
+    return normalizedEvent({
+      eventKey: `claude:usage-gap:${nativeId}`,
+      type: "usage",
+      occurredAt,
+      payload: {
+        role: "assistant", contentFormat: "json", captureStatus: "complete",
+        gap: true, reason: "usage_unavailable",
+      },
+      sourceEndOffset,
+    });
+  }
+  const cacheCreation = usage.cache_creation && typeof usage.cache_creation === "object"
+    ? usage.cache_creation : {};
+  const details = usage.output_tokens_details && typeof usage.output_tokens_details === "object"
+    ? usage.output_tokens_details : {};
+  const messageId = usageLabel(message.id);
+  const payload = {
+    role: "assistant",
+    contentFormat: "json",
+    captureStatus: "complete",
+    provider: "anthropic",
+    model,
+    providerRequestId: usageLabel(entry.requestId),
+    messageId,
+    stopReason: usageLabel(message.stop_reason),
+    serviceTier: usageLabel(usage.service_tier),
+    effort: usageLabel(entry.effort),
+    sidechain: entry.isSidechain === true,
+    latencyMs: null,
+    inputTokens: usageInt(usage.input_tokens),
+    outputTokens: usageInt(usage.output_tokens),
+    cacheReadTokens: usageInt(usage.cache_read_input_tokens),
+    cacheWriteTokens: usageInt(usage.cache_creation_input_tokens),
+    cacheWrite1hTokens: usageInt(cacheCreation.ephemeral_1h_input_tokens),
+    cacheWrite5mTokens: usageInt(cacheCreation.ephemeral_5m_input_tokens),
+    reasoningTokens: usageInt(details.thinking_tokens),
+  };
+  return normalizedEvent({
+    eventKey: `claude:usage:${messageId || nativeId}`,
+    type: "usage",
+    occurredAt,
+    payload,
+    sourceEndOffset,
+  });
+}
+
+/**
+ * Content-free outcome scalars for one tool_result block, joining the
+ * structured `toolUseResult` the host attached to the record and the tool_use
+ * timestamp observed earlier in the same suffix window.
+ */
+function toolOutcomeFromEntry(entry, block, evidence) {
+  const raw = entry?.toolUseResult !== null && typeof entry?.toolUseResult === "object" &&
+    !Array.isArray(entry.toolUseResult) ? entry.toolUseResult : null;
+  const failed = block.is_error === true || raw?.status === "failed" || raw?.is_error === true;
+  const calledMs = evidence.toolUseTimestamps instanceof Map
+    ? evidence.toolUseTimestamps.get(String(block.tool_use_id ?? "")) : undefined;
+  const resultMs = Date.parse(String(entry?.timestamp ?? ""));
+  const durationMs = Number.isFinite(calledMs) && Number.isFinite(resultMs) && resultMs >= calledMs
+    ? Math.min(resultMs - calledMs, 86_400_000) : null;
+  const outputBytes = bodyBytes(stableClone(block.content ?? null), "json").length;
+  const resolvedModel = typeof raw?.resolvedModel === "string" &&
+    USAGE_MODEL_PATTERN.test(raw.resolvedModel) ? raw.resolvedModel : null;
+  return {
+    failed: Boolean(failed),
+    interrupted: raw?.interrupted === true,
+    ...(typeof raw?.status === "string" ? { status: reasonCode(raw.status) } : {}),
+    ...(durationMs === null ? {} : { durationMs }),
+    outputBytes,
+    ...(resolvedModel === null ? {} : { resolvedModel }),
+  };
+}
+
+function thinkingEvent({ nativeId, index, text, occurredAt, sourceEndOffset }) {
+  const payload = boundedCompletePayload({
+    role: "assistant",
+    contentFormat: "utf8",
+    captureStatus: "complete",
+    text,
+  }, { role: "assistant", body: text, format: "utf8" });
+  return normalizedEvent({
+    eventKey: `claude:${nativeId}:thinking:${index}`,
+    type: "message",
+    occurredAt,
+    payload,
+    sourceEndOffset,
+    part: "thinking",
+  });
+}
+
+const MAX_INLINE_ATTACHMENT_BYTES = 8 * 1024;
+
 /**
  * Normalize one current Claude transcript record into zero or more archive
  * events. Text is never trimmed or prefix-truncated. Unsupported/oversized
  * bodies become explicit digest-only events, so advancing the byte cursor
- * cannot silently turn a capture gap into success.
+ * cannot silently turn a capture gap into success. Opaque host tokens
+ * (`atis-latch`) are never read at all.
  */
 export function normalizeClaudeTranscriptEntry(entry, evidence) {
+  const recordType = entry?.type;
+  const sourceEndOffset = evidence.endOffset;
+  if (recordType === "queue-operation") {
+    // A user message queued mid-turn. Only the enqueue marks a queued message;
+    // the content itself reaches the archive through the transcript when the
+    // host delivers it as a real user turn.
+    if (entry.operation !== "enqueue") return [];
+    const occurredAt = entry.timestamp || evidence.occurredAt;
+    return [normalizedEvent({
+      eventKey: `claude:queued:${digest(`${entry.timestamp ?? ""}\0${evidence.byteOffset}`)}`,
+      type: "checkpoint",
+      occurredAt,
+      payload: { contentFormat: "json", captureStatus: "complete", kind: "queued_message" },
+      sourceEndOffset,
+    })];
+  }
+  if (recordType === "attachment") {
+    const occurredAt = entry.timestamp || evidence.occurredAt;
+    const attachment = entry.attachment !== null && typeof entry.attachment === "object"
+      ? entry.attachment : {};
+    const attachmentType = boundedIdentifier(attachment.type || "unknown", 100);
+    const stableBody = stableClone(attachment);
+    const bytes = bodyBytes(stableBody, "json");
+    const payload = bytes.length <= MAX_INLINE_ATTACHMENT_BYTES
+      ? boundedCompletePayload({
+        contentFormat: "json", captureStatus: "complete",
+        kind: "attachment", attachmentType, body: stableBody,
+      }, { body: stableBody, format: "json", extra: { kind: "attachment", attachmentType } })
+      : digestOnlyPayload({
+        body: bytes, status: "truncated", reason: "attachment_body_too_large",
+        extra: { kind: "attachment", attachmentType },
+      });
+    return [normalizedEvent({
+      eventKey: `claude:attachment:${entry.uuid || `offset-${evidence.byteOffset}`}`,
+      type: "checkpoint",
+      occurredAt,
+      payload,
+      sourceEndOffset,
+    })];
+  }
   const message = entry?.message;
   if (!message || !["user", "assistant"].includes(message.role)) return [];
   const role = message.role;
   const occurredAt = entry.timestamp || evidence.occurredAt;
-  const sourceEndOffset = evidence.endOffset;
   const nativeId = nativeEntryId(entry, evidence);
+  const usageEvents = role === "assistant"
+    ? [usageEventFromEntry(entry, { nativeId, occurredAt, sourceEndOffset })]
+    : [];
   if (typeof message.content === "string") {
-    return [textEvent({ nativeId, index: 0, role, text: message.content, occurredAt, sourceEndOffset })];
+    return [textEvent({ nativeId, index: 0, role, text: message.content, occurredAt, sourceEndOffset }), ...usageEvents];
   }
   if (!Array.isArray(message.content)) {
     return [unsupportedBlockEvent({
@@ -275,20 +485,28 @@ export function normalizeClaudeTranscriptEntry(entry, evidence) {
       block: message.content,
       occurredAt,
       sourceEndOffset,
-    })];
+    }), ...usageEvents];
   }
   if (message.content.length === 0) {
-    return [textEvent({ nativeId, index: 0, role, text: "", occurredAt, sourceEndOffset })];
+    return [textEvent({ nativeId, index: 0, role, text: "", occurredAt, sourceEndOffset }), ...usageEvents];
   }
-  return message.content.map((block, index) => {
+  return [...message.content.flatMap((block, index) => {
     if (!block || typeof block !== "object") {
-      return unsupportedBlockEvent({ nativeId, index, role, block, occurredAt, sourceEndOffset });
+      return [unsupportedBlockEvent({ nativeId, index, role, block, occurredAt, sourceEndOffset })];
     }
     if (block.type === "text" && typeof block.text === "string") {
-      return textEvent({ nativeId, index, role, text: block.text, occurredAt, sourceEndOffset });
+      return [textEvent({ nativeId, index, role, text: block.text, occurredAt, sourceEndOffset })];
+    }
+    if (block.type === "thinking" && typeof block.thinking === "string") {
+      // Reasoning content, captured as a marked message part so a session
+      // with thinking no longer reads as partial. Empty blocks (signature
+      // only) carry no content and produce no event.
+      return block.thinking.length > 0
+        ? [thinkingEvent({ nativeId, index, text: block.thinking, occurredAt, sourceEndOffset })]
+        : [];
     }
     if (block.type === "tool_use") {
-      return toolEvent({
+      return [toolEvent({
         nativeId,
         index,
         type: "tool_call",
@@ -297,10 +515,10 @@ export function normalizeClaudeTranscriptEntry(entry, evidence) {
         body: block.input,
         occurredAt,
         sourceEndOffset,
-      });
+      })];
     }
     if (block.type === "tool_result") {
-      return toolEvent({
+      return [toolEvent({
         nativeId,
         index,
         type: "tool_result",
@@ -310,13 +528,15 @@ export function normalizeClaudeTranscriptEntry(entry, evidence) {
         occurredAt,
         sourceEndOffset,
         failed: block.is_error,
-      });
+        hostResult: entry?.toolUseResult,
+        outcome: toolOutcomeFromEntry(entry, block, evidence),
+      })];
     }
     if (["image", "document", "artifact", "file"].includes(block.type)) {
-      return artifactEvent({ nativeId, index, role, block, occurredAt, sourceEndOffset });
+      return [artifactEvent({ nativeId, index, role, block, occurredAt, sourceEndOffset })];
     }
-    return unsupportedBlockEvent({ nativeId, index, role, block, occurredAt, sourceEndOffset });
-  });
+    return [unsupportedBlockEvent({ nativeId, index, role, block, occurredAt, sourceEndOffset })];
+  }), ...usageEvents];
 }
 
 export function normalizeMalformedClaudeTranscriptLine(rawBytes, evidence) {
@@ -418,11 +638,39 @@ export function normalizeHostMessageEvent({
   };
 }
 
+function collectClaudeMetadata(metadata, entry) {
+  const bounded = (value, max) =>
+    typeof value === "string" && value.length > 0 && value.length <= max &&
+    !/[\u0000-\u001f\u007f]/.test(value) ? value : undefined;
+  const hostVersion = bounded(entry.version, 64);
+  if (hostVersion) metadata.hostVersion = hostVersion;
+  const entrypoint = bounded(entry.entrypoint, 64);
+  if (entrypoint) metadata.entrypoint = entrypoint;
+  const userType = bounded(entry.userType, 64);
+  if (userType) metadata.userType = userType;
+  const effort = bounded(entry.effort, 64);
+  if (effort) metadata.effort = effort;
+  const permissionMode = entry.type === "permission-mode"
+    ? bounded(entry.permissionMode, 64)
+    : bounded(entry.permissionMode, 64);
+  if (permissionMode) metadata.permissionMode = permissionMode;
+  if (entry.type === "ai-title") {
+    const title = bounded(entry.aiTitle ?? entry.title, 512);
+    if (title) metadata.title = title;
+  }
+  const gitBranch = bounded(entry.gitBranch, 512);
+  if (gitBranch) metadata.gitBranch = gitBranch;
+  const cwd = bounded(entry.cwd, 2048);
+  if (cwd) metadata.cwd = cwd;
+}
+
 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;
   const suffix = bytes.subarray(start);
   const events = [];
+  const metadata = {};
+  const toolUseTimestamps = new Map();
   let position = 0;
   while (position < suffix.length) {
     const newline = suffix.indexOf(0x0a, position);
@@ -439,14 +687,95 @@ export async function readClaudeTranscriptSuffix(path, cursor, sessionHash) {
       endOffset,
       rawBytes,
       occurredAt: new Date().toISOString(),
+      toolUseTimestamps,
     };
     try {
-      events.push(...normalizeClaudeTranscriptEntry(JSON.parse(raw), evidence));
+      const entry = JSON.parse(raw);
+      if (entry !== null && typeof entry === "object") {
+        collectClaudeMetadata(metadata, entry);
+        if (entry.type === "assistant" && Array.isArray(entry.message?.content)) {
+          const calledMs = Date.parse(String(entry.timestamp ?? ""));
+          for (const block of entry.message.content) {
+            if (block && typeof block === "object" && block.type === "tool_use" &&
+                typeof block.id === "string" && Number.isFinite(calledMs)) {
+              toolUseTimestamps.set(block.id, calledMs);
+            }
+          }
+        }
+      }
+      events.push(...normalizeClaudeTranscriptEntry(entry, evidence));
     } catch {
       events.push(normalizeMalformedClaudeTranscriptLine(rawBytes, evidence));
     }
   }
-  return { events, observedEndOffset: start + position };
+  // Claude repeats the same usage record on every JSONL line of a multi-block
+  // message. One usage event per message.id, keep-last: later lines carry the
+  // completed totals. A gap event is withdrawn the moment any line of the
+  // same message produced a real usage record.
+  const usageByKey = new Map();
+  for (const event of events) {
+    if (event.type === "usage") usageByKey.set(event.eventKey, event);
+  }
+  const usageKeysWithData = new Set(
+    [...usageByKey.keys()].filter((key) => key.startsWith("claude:usage:")),
+  );
+  const emittedUsageKeys = new Set();
+  const deduped = [];
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index];
+    if (event.type === "usage") {
+      if (emittedUsageKeys.has(event.eventKey)) continue;
+      if (event.eventKey.startsWith("claude:usage-gap:")) {
+        const nativeId = event.eventKey.slice("claude:usage-gap:".length);
+        if (usageKeysWithData.has(`claude:usage:${nativeId}`)) continue;
+      }
+      emittedUsageKeys.add(event.eventKey);
+    }
+    deduped.unshift(event);
+  }
+  return { events: deduped, observedEndOffset: start + position, metadata };
+}
+
+export function buildClaudeMetadataPayload(metadata, { installationId, deviceContext }) {
+  const payload = {};
+  for (const field of ["hostVersion", "entrypoint", "userType", "permissionMode", "effort", "title"]) {
+    if (typeof metadata[field] === "string" && metadata[field].length > 0) {
+      payload[field] = metadata[field];
+    }
+  }
+  if (typeof metadata.cwd === "string" && metadata.cwd.length > 0) {
+    // The path itself leaves the device only under an explicit org policy
+    // (deviceContext=full); the salted hash and basename always travel so
+    // spend can still be grouped per repository.
+    payload.cwdHash = digest(`halofy-cwd-v1\0${installationId}\0${metadata.cwd}`);
+    const segments = metadata.cwd.split(/[\\/]/).filter((segment) => segment.length > 0);
+    const base = segments.length > 0 ? segments[segments.length - 1].slice(0, 256) : "";
+    if (base) payload.cwdBasename = base;
+    if (deviceContext === "full") payload.cwdPath = metadata.cwd;
+  }
+  if (typeof metadata.gitBranch === "string" && metadata.gitBranch.length > 0 &&
+      deviceContext === "full") {
+    payload.gitBranch = metadata.gitBranch;
+  }
+  if (typeof metadata.startSource === "string" && metadata.startSource.length > 0) {
+    payload.startSource = metadata.startSource;
+  }
+  if (typeof metadata.closeReason === "string" && metadata.closeReason.length > 0) {
+    payload.closeReason = metadata.closeReason;
+  }
+  if (typeof metadata.subagentType === "string" && metadata.subagentType.length > 0) {
+    payload.subagentType = metadata.subagentType;
+  }
+  return payload;
+}
+
+export function claudeMetadataEvent(payload) {
+  return normalizedEvent({
+    eventKey: `claude:metadata:${digest(stableJson(payload))}`,
+    type: "metadata",
+    occurredAt: new Date().toISOString(),
+    payload: { contentFormat: "json", captureStatus: "complete", ...payload },
+  });
 }
 
 export class CursorStore {
@@ -493,4 +822,31 @@ export class CursorStore {
       return current;
     });
   }
+
+  // Usage-gap diagnostics (PRD §8.3): a content-free count of host records
+  // the adapter could not read usage from, reported on the next heartbeat as
+  // a delta and cleared only after successful delivery.
+  async peekUsageGaps() {
+    const state = await readJson(this.path, { version: 1, sessions: {} });
+    const count = Number(state.usageGaps ?? 0);
+    return Number.isSafeInteger(count) && count > 0 ? count : 0;
+  }
+
+  async bumpUsageGaps(count) {
+    if (!Number.isSafeInteger(count) || count <= 0) return;
+    await withFileLock(this.lockPath, async () => {
+      const state = await readJson(this.path, { version: 1, sessions: {} });
+      state.usageGaps = Math.max(0, Number(state.usageGaps ?? 0) || 0) + count;
+      await writePrivateFile(this.path, `${JSON.stringify(state)}\n`);
+    });
+  }
+
+  async clearUsageGaps(delivered) {
+    if (!Number.isSafeInteger(delivered) || delivered <= 0) return;
+    await withFileLock(this.lockPath, async () => {
+      const state = await readJson(this.path, { version: 1, sessions: {} });
+      state.usageGaps = Math.max(0, (Number(state.usageGaps ?? 0) || 0) - delivered);
+      await writePrivateFile(this.path, `${JSON.stringify(state)}\n`);
+    });
+  }
 }

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.4.0";
-export const RUNTIME_VERSION = "0.4.0";
-export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-08-29";
+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";