@halofy/agent-connect 0.4.0 → 0.5.0

package/README.md

@@ -19,7 +19,7 @@ agent connections:
 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.0 install <client-kind> \
   --server https://app.halofy.ai \
   --claim '<one-time-claim>'
 ```

package/package.json

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

package/src/claude-hook.mjs

@@ -61,10 +61,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) {
@@ -124,7 +124,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 +134,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/installer-cli.mjs

@@ -95,6 +95,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);

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)
@@ -251,21 +269,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 +454,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 +484,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 +497,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 +607,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 +656,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 +791,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/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.0";
+export const RUNTIME_VERSION = "0.5.0";
+export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-08-29.2";