@halofy/agent-connect 0.5.0 → 0.6.0

package/src/installer-cli.mjs

@@ -4,6 +4,8 @@ import { createInterface } from "node:readline/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import {
+  fetchClaimDisclosure,
+  fetchClaimDisclosures,
   heartbeatInstalledConnection,
   installLocalConnection,
   installRuntimeBundle,
@@ -15,9 +17,50 @@ import { CLIENT_KINDS, lifecycleClient } from "./client-registry.mjs";
 import { defaultRuntimeDirectory } from "./storage.mjs";
 import { DISCLOSURE_VERSION, INSTALLER_VERSION } from "./version.mjs";
 
+const CLAIM_PATTERN = /^hsc_[A-Za-z0-9_-]{43}$/;
+
+function parseAllInstallerArgs(argv) {
+  const values = new Map();
+  for (let index = 2; index < argv.length; index += 1) {
+    const name = argv[index];
+    if (!["--server", "--claims", "--claude-project"].includes(name) || values.has(name)) {
+      throw new Error("unsupported or duplicate installer argument");
+    }
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) throw new Error(`${name} requires a value`);
+    values.set(name, value);
+    index += 1;
+  }
+  const serverUrl = values.get("--server");
+  const rawClaims = values.get("--claims");
+  const usage = "Usage: agent-connect install all --server <https-url> --claims <client>=<one-use-claim>[,...]";
+  if (!serverUrl || !rawClaims) throw new Error(usage);
+  const pairs = rawClaims.split(",");
+  if (pairs.length < 1 || pairs.length > CLIENT_KINDS.length) throw new Error(usage);
+  const selections = [];
+  const kinds = new Set();
+  for (const pair of pairs) {
+    const separator = pair.indexOf("=");
+    const clientKind = separator === -1 ? "" : pair.slice(0, separator);
+    const claim = separator === -1 ? "" : pair.slice(separator + 1);
+    if (!CLIENT_KINDS.includes(clientKind) || !CLAIM_PATTERN.test(claim) || kinds.has(clientKind)) {
+      throw new Error(usage);
+    }
+    kinds.add(clientKind);
+    selections.push({ clientKind, claim });
+  }
+  return {
+    mode: "all",
+    selections,
+    serverUrl,
+    projectRoot: resolve(values.get("--claude-project") || process.cwd()),
+  };
+}
+
 export function parseInstallerArgs(argv) {
   const command = argv[0];
   const clientKind = argv[1];
+  if (command === "install" && clientKind === "all") return parseAllInstallerArgs(argv);
   const values = new Map();
   for (let index = 2; index < argv.length; index += 1) {
     const name = argv[index];
@@ -36,6 +79,7 @@ export function parseInstallerArgs(argv) {
     throw new Error("Usage: agent-connect install <supported-client> --server <https-url> --claim <one-use-claim>");
   }
   return {
+    mode: "single",
     clientKind,
     serverUrl,
     claim,
@@ -81,8 +125,20 @@ export function detectClient(clientKind) {
   return String(result.stdout || result.stderr || "").trim().slice(0, 128) || "detected";
 }
 
-export function disclosureText({ serverUrl, projectRoot, clientKind, clientVersion }) {
-  const client = lifecycleClient(clientKind);
+/** Non-throwing detection probe for the install-all sweep. */
+export async function probeClient(clientKind, {
+  detectClaude = detectClaudeCode,
+  detectHost = detectClient,
+} = {}) {
+  try {
+    const version = clientKind === "claude-code" ? await detectClaude() : await detectHost(clientKind);
+    return { detected: true, version };
+  } catch (error) {
+    return { detected: false, reason: error?.message || "not detected" };
+  }
+}
+
+function captureCategories(client) {
   const observedCategories = [
     ["user messages", client.capabilities.userMessages],
     ["assistant messages", client.capabilities.assistantMessages],
@@ -100,17 +156,27 @@ export function disclosureText({ serverUrl, projectRoot, clientKind, clientVersi
     ["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);
+  return {
+    supported: observedCategories.filter(([, value]) => value === true).map(([name]) => name),
+    unsupported: observedCategories.filter(([, value]) => value !== true).map(([name]) => name),
+  };
+}
+
+export function disclosureText({ serverUrl, projectRoot, clientKind, clientVersion, organization = null }) {
+  const client = lifecycleClient(clientKind);
+  const { supported, unsupported } = captureCategories(client);
   return [
     `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",
@@ -128,6 +194,55 @@ export function disclosureText({ serverUrl, projectRoot, clientKind, clientVersi
   ].join("\n");
 }
 
+/**
+ * One disclosure for the whole sweep: shared header, one capture-category
+ * section per detected host, and an explicit statement of which minted claims
+ * will expire unused. One CONNECT then covers exactly the listed hosts —
+ * explicit per-host consent, never a silent fan-out.
+ */
+export function allDisclosureText({ serverUrl, projectRoot, organization = null, hosts, unusedKinds = [] }) {
+  const lines = [
+    "Halofy all-agents lifecycle connection",
+    `Installer: @halofy/agent-connect@${INSTALLER_VERSION}`,
+    `Server: ${new URL(serverUrl).origin}`,
+    // The server named by --server identifies the organization this command
+    // binds to, so a spoofed command is recognizable before CONNECT.
+    `Organization: ${organization || "unverified (the server did not identify this command's organization)"}`,
+    `Project: ${projectRoot}`,
+    `Hosts to be connected: ${hosts.map((host) => lifecycleClient(host.clientKind).label).join(", ")}`,
+    "",
+    "Each host gets its own installation binding, capability record, and connection status:",
+  ];
+  for (const host of hosts) {
+    const client = lifecycleClient(host.clientKind);
+    const { supported, unsupported } = captureCategories(client);
+    lines.push(
+      "",
+      `--- ${client.label} (${host.clientVersion}) ---`,
+      `Supported capture categories: ${supported.length > 0 ? supported.join(", ") : "none"}.`,
+      `Unsupported capture categories: ${unsupported.length > 0 ? unsupported.join(", ") : "none"}.`,
+      client.coverage === "complete"
+        ? "This reviewed host surface can report complete coverage when all declared evidence is observed."
+        : `This host has partial coverage (${client.reason}); missing categories remain explicit.`,
+    );
+  }
+  if (unusedKinds.length > 0) {
+    lines.push(
+      "",
+      `Claims for ${unusedKinds.map((kind) => lifecycleClient(kind).label).join(", ")} were issued ` +
+      "but those hosts were not detected here; they expire unused within 10 minutes.",
+    );
+  }
+  lines.push(
+    "",
+    "Authorized organization managers may review retained conversations and summaries.",
+    "This does not scan historical files, other applications, clipboard, keystrokes, or other agents.",
+    "Disconnecting stops future capture but does not erase retained data.",
+    `Disclosure: ${DISCLOSURE_VERSION}`,
+  );
+  return lines.join("\n");
+}
+
 export async function confirmDisclosure({ input = process.stdin, output = process.stdout } = {}) {
   if (!input.isTTY || !output.isTTY) throw new Error("interactive terminal confirmation is required");
   const prompt = createInterface({ input, output });
@@ -140,6 +255,136 @@ export async function confirmDisclosure({ input = process.stdin, output = proces
   return true;
 }
 
+async function configureHost(clientKind, common, { claudeConfigPath } = {}) {
+  if (clientKind === "claude-code") {
+    return configureClaudeProject({ ...common, ...(claudeConfigPath ? { claudeConfigPath } : {}) });
+  }
+  if (clientKind === "cursor") return configureCursor(common);
+  if (clientKind === "gemini-cli") return configureGemini(common);
+  if (clientKind === "kimi-cli") return configureKimi(common);
+  if (clientKind === "vscode") return configureVscode(common);
+  if (clientKind === "codex") return configureCodex(common);
+  if (clientKind === "cline") return configureCline(common);
+  throw new Error("the selected adapter is not packaged yet");
+}
+
+async function runAllInstaller(input, {
+  root,
+  output,
+  detectClaude,
+  detectHost,
+  confirm,
+  fetchImpl,
+  sourceRoot,
+  claudeConfigPath,
+}) {
+  const probes = [];
+  for (const selection of input.selections) {
+    probes.push({ ...selection, probe: await probeClient(selection.clientKind, { detectClaude, detectHost }) });
+  }
+  const detected = probes.filter((entry) => entry.probe.detected);
+  const skipped = probes.filter((entry) => !entry.probe.detected)
+    .map((entry) => ({ clientKind: entry.clientKind, reason: "not_detected" }));
+  if (detected.length === 0) {
+    throw new Error("no claimed agents were detected on this machine: " +
+      probes.map((entry) => `${lifecycleClient(entry.clientKind).label} (${entry.probe.reason})`).join("; "));
+  }
+
+  // One batch disclosure call spends one throttle token for the whole sweep.
+  const disclosures = await fetchClaimDisclosures({
+    serverUrl: input.serverUrl,
+    claims: input.selections.map((selection) => selection.claim),
+    fetchImpl,
+  });
+  let organization = null;
+  if (disclosures !== null) {
+    const organizations = new Set();
+    for (let index = 0; index < input.selections.length; index += 1) {
+      const disclosure = disclosures[index];
+      if (!disclosure) continue;
+      // A claim minted for one client kind pasted behind another label is a
+      // spoofed or reassembled command — refuse before any consent prompt.
+      if (disclosure.clientKind !== null && disclosure.clientKind !== input.selections[index].clientKind) {
+        throw new Error(`the claim labeled ${input.selections[index].clientKind} was issued for ` +
+          `${disclosure.clientKind}; refuse this command and generate a fresh one`);
+      }
+      if (disclosure.organization) organizations.add(disclosure.organization);
+    }
+    if (organizations.size > 1) {
+      throw new Error("the claims in this command belong to different organizations; " +
+        "refuse this command and generate a fresh one");
+    }
+    organization = organizations.size === 1 ? [...organizations][0] : null;
+  }
+
+  output.write(`${allDisclosureText({
+    serverUrl: input.serverUrl,
+    projectRoot: input.projectRoot,
+    organization,
+    hosts: detected.map((entry) => ({ clientKind: entry.clientKind, clientVersion: entry.probe.version })),
+    unusedKinds: skipped.map((entry) => entry.clientKind),
+  })}\n`);
+  await confirm();
+
+  // The reviewed runtime bundle installs exactly once for the whole sweep.
+  const bundle = await installRuntimeBundle({ root, ...(sourceRoot ? { sourceRoot } : {}) });
+  const results = [];
+  for (const host of detected) {
+    try {
+      const installed = await installLocalConnection({
+        serverUrl: input.serverUrl,
+        claim: host.claim,
+        clientKind: host.clientKind,
+        root,
+        fetchImpl,
+        sendHeartbeat: false,
+      });
+      const configured = await configureHost(host.clientKind, {
+        projectRoot: input.projectRoot,
+        installationId: installed.installationId,
+        serverUrl: input.serverUrl,
+        runtimePath: bundle.runtimePath,
+      }, { claudeConfigPath });
+      let heartbeat = false;
+      try {
+        heartbeat = await heartbeatInstalledConnection({
+          installationId: installed.installationId, root, fetchImpl,
+        });
+      } catch {
+        heartbeat = false;
+      }
+      results.push({
+        clientKind: host.clientKind,
+        status: heartbeat ? "configured_heartbeat_verified" : "configured_heartbeat_unavailable",
+        installationId: installed.installationId,
+        proofStorage: installed.proofStorage,
+        configuredPaths: configured.configuredPaths || [configured.mcpPath, configured.settingsPath],
+        replacedLegacyMcpEntries: configured.replacedLegacyMcpEntries || 0,
+        nextStep: `Restart ${lifecycleClient(host.clientKind).label}, then check the connection in Halofy.`,
+      });
+    } catch (error) {
+      // One host failing must not abort the others; the failure is reported,
+      // never hidden.
+      skipped.push({
+        clientKind: host.clientKind,
+        reason: `failed:${(error?.message || "install_error").slice(0, 200)}`,
+      });
+    }
+  }
+  if (results.length === 0) {
+    throw new Error("every detected agent failed to install: " +
+      skipped.map((entry) => `${entry.clientKind} (${entry.reason})`).join("; "));
+  }
+  return {
+    status: skipped.some((entry) => entry.reason.startsWith("failed:"))
+      ? "completed_with_failures" : "completed",
+    installerVersion: INSTALLER_VERSION,
+    publishedPackage: true,
+    results,
+    skipped,
+  };
+}
+
 export async function runInstaller(argv, {
   root = defaultRuntimeDirectory(),
   output = process.stdout,
@@ -151,8 +396,22 @@ export async function runInstaller(argv, {
   claudeConfigPath,
 } = {}) {
   const input = parseInstallerArgs(argv);
+  if (input.mode === "all") {
+    return runAllInstaller(input, {
+      root, output, detectClaude, detectHost, confirm, fetchImpl, sourceRoot, claudeConfigPath,
+    });
+  }
   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({
@@ -170,21 +429,7 @@ export async function runInstaller(argv, {
     serverUrl: input.serverUrl,
     runtimePath: bundle.runtimePath,
   };
-  const configured = input.clientKind === "claude-code"
-    ? await configureClaudeProject({ ...common, ...(claudeConfigPath ? { claudeConfigPath } : {}) })
-    : input.clientKind === "cursor"
-      ? await configureCursor(common)
-      : input.clientKind === "gemini-cli"
-        ? await configureGemini(common)
-        : input.clientKind === "kimi-cli"
-          ? await configureKimi(common)
-          : input.clientKind === "vscode"
-            ? await configureVscode(common)
-            : input.clientKind === "codex"
-              ? await configureCodex(common)
-              : input.clientKind === "cline"
-                ? await configureCline(common)
-                : (() => { throw new Error("the selected adapter is not packaged yet"); })();
+  const configured = await configureHost(input.clientKind, common, { claudeConfigPath });
   let heartbeat = false;
   try {
     heartbeat = await heartbeatInstalledConnection({

package/src/runtime.mjs

@@ -2,12 +2,10 @@ import { createHash, randomBytes } from "node:crypto";
 import { join } from "node:path";
 import { BoundedEncryptedQueue } from "./queue.mjs";
 import {
-  buildClaudeMetadataPayload,
-  claudeMetadataEvent,
   CursorStore,
   deriveSessionHash,
-  readClaudeTranscriptSuffix,
 } from "./session.mjs";
+import { claudeTranscriptDriver } from "./transcript-drivers/claude.mjs";
 import { SignedRuntimeTransport } from "./transport.mjs";
 import { readJson, withFileLock, writePrivateFile } from "./storage.mjs";
 import { RUNTIME_VERSION } from "./version.mjs";
@@ -113,26 +111,30 @@ export class LifecycleRuntime {
   }
 
   async captureClaudeTranscript(hostSessionId, transcriptPath, sessionFacts = {}) {
+    return this.captureHostTranscript(hostSessionId, claudeTranscriptDriver, transcriptPath, sessionFacts);
+  }
+
+  async captureHostTranscript(hostSessionId, driver, 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 suffix = await driver.readSuffix(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(
+      const metadataPayload = driver.buildMetadataPayload(
         { ...suffix.metadata, ...sessionFacts },
         { installationId: this.connection.installationId, deviceContext: policy.deviceContext },
       );
       if (Object.keys(metadataPayload).length > 0) {
-        const metadataEvent = claudeMetadataEvent(metadataPayload);
+        const metadataEvent = driver.metadataEvent(metadataPayload);
         if (!recentEventKeys.has(metadataEvent.eventKey)) unseenEvents.push(metadataEvent);
       }
       const usageGaps = unseenEvents.filter((event) =>
-        event.type === "usage" && event.eventKey.startsWith("claude:usage-gap:")).length;
+        event.type === "usage" && event.eventKey.startsWith(driver.usageGapPrefix)).length;
       const result = unseenEvents.length === 0
         ? { queued: 0 }
         : await this.queue.enqueueSessionEvents(sessionHash, unseenEvents, {
@@ -144,8 +146,11 @@ export class LifecycleRuntime {
       // normalized event is already durable in the encrypted queue. Advancing
       // this byte cursor prevents unbounded reparsing without advancing the
       // separately acknowledged event sequence.
-      if (suffix.observedEndOffset > cursor.byteOffset) {
-        await this.cursors.update(sessionHash, { byteOffset: suffix.observedEndOffset });
+      const patch = {};
+      if (suffix.observedEndOffset > cursor.byteOffset) patch.byteOffset = suffix.observedEndOffset;
+      if (suffix.hostState !== undefined) patch.hostState = suffix.hostState;
+      if (Object.keys(patch).length > 0) {
+        await this.cursors.update(sessionHash, patch);
       }
       await this.cursors.rememberEventKeys(sessionHash, unseenEvents.map((event) => event.eventKey));
       if (usageGaps > 0) await this.cursors.bumpUsageGaps(usageGaps);

package/src/session.mjs

@@ -86,7 +86,7 @@ function boundedCompletePayload(payload, { role, body, format = "json", extra =
   });
 }
 
-function normalizedEvent({ eventKey, type, occurredAt, payload, sourceEndOffset, part }) {
+export function normalizedEvent({ eventKey, type, occurredAt, payload, sourceEndOffset, part }) {
   const {
     role,
     contentFormat = "json",
@@ -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}`);
@@ -269,15 +300,15 @@ export function stripInjectedContext(value) {
   return String(value);
 }
 
-function usageInt(value) {
+export function usageInt(value) {
   return Number.isSafeInteger(value) && value >= 0 && value < 2 ** 31 ? value : null;
 }
 
-function usageLabel(value) {
+export 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}$/;
+export const USAGE_MODEL_PATTERN = /^[A-Za-z0-9._:/-]{1,128}$/;
 
 /**
  * One host-reported usage record per assistant message (PRD §8.1). Claude
@@ -738,15 +769,19 @@ export function buildClaudeMetadataPayload(metadata, { installationId, deviceCon
   return payload;
 }
 
-export function claudeMetadataEvent(payload) {
+export function hostMetadataEvent(namespace, payload) {
   return normalizedEvent({
-    eventKey: `claude:metadata:${digest(stableJson(payload))}`,
+    eventKey: `${namespace}:metadata:${digest(stableJson(payload))}`,
     type: "metadata",
     occurredAt: new Date().toISOString(),
     payload: { contentFormat: "json", captureStatus: "complete", ...payload },
   });
 }
 
+export function claudeMetadataEvent(payload) {
+  return hostMetadataEvent("claude", payload);
+}
+
 export class CursorStore {
   constructor(root) {
     this.path = join(root, "cursors.json");

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/transcript-drivers/claude.mjs

@@ -0,0 +1,33 @@
+import {
+  buildClaudeMetadataPayload,
+  claudeMetadataEvent,
+  readClaudeTranscriptSuffix,
+} from "../session.mjs";
+
+/**
+ * Thin delegation over the reviewed Claude Code adapter. The claude path is
+ * frozen — its eventKeys are pinned by the golden fixture test and must stay
+ * byte-identical for server-side dedupe history. Claude Code hooks pass the
+ * transcript path directly, so this driver has no locate step.
+ */
+export const claudeTranscriptDriver = {
+  clientKind: "claude-code",
+  eventKeyNamespace: "claude",
+  usageGapPrefix: "claude:usage-gap:",
+
+  async locate() {
+    return null;
+  },
+
+  readSuffix(path, cursor, sessionHash) {
+    return readClaudeTranscriptSuffix(path, cursor, sessionHash);
+  },
+
+  buildMetadataPayload(metadata, context) {
+    return buildClaudeMetadataPayload(metadata, context);
+  },
+
+  metadataEvent(payload) {
+    return claudeMetadataEvent(payload);
+  },
+};