@scotthuang/agent-knock-knock 0.14.16 → 0.15.0

package/dist/src/claude-local-transcript-provider.js

@@ -1,7 +1,8 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
+import { defaultClaudeHome, claudeTranscriptAnchorFingerprint, claudeTranscriptFileId as transcriptFileId, resolveClaudeTranscriptHome, validatedClaudeConfigDir } from "./claude-transcript-config.js";
+export { defaultClaudeHome, claudeTranscriptAnchorFingerprint } from "./claude-transcript-config.js";
 import { isClaudeAgentIdleState } from "./claude-terminal-agent-adapter.js";
 import { claudeLifecycleSourceVersionSupported, claudeRuntimeLifecycleCompatibilityProfile, DEFAULT_CLAUDE_LIFECYCLE_VERSION, } from "./claude-lifecycle-compatibility.js";
 import { assertParentsPrecedeChildren, earliestClaudeTranscriptRecordOffset, initialClaudeTranscriptCheckpointRecords, orderClaudePrewrittenAttachments } from "./claude-transcript-record-order.js";
@@ -11,16 +12,11 @@ import { validateTerminalSubmissionAcceptanceEvidence } from "./terminal-submiss
 const CLAUDE_TRANSCRIPT_ANCHOR_VERSION = 1;
 const CLAUDE_TRANSCRIPT_MAX_TURN_BYTES = 64 * 1024 * 1024;
 const CLAUDE_SESSION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
-const MINIMUM_CLAUDE_TRANSCRIPT_VERSION = [2, 1, 198];
 const CLAUDE_TRANSCRIPT_VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u;
 const NO_FOLLOW_FLAG = typeof fs.constants.O_NOFOLLOW === "number"
     ? fs.constants.O_NOFOLLOW
     : 0;
 const CLAUDE_HISTORICAL_METADATA_MAX_BYTES = 1024 * 1024;
-export function defaultClaudeHome() {
-    const configured = process.env.CLAUDE_CONFIG_DIR?.trim();
-    return configured || path.join(os.homedir(), ".claude");
-}
 /** List exact, root-interactive Claude sessions from owner-private transcripts. */
 export function listClaudeHistoricalSessions(options) {
     if (!options.cwd || !path.isAbsolute(options.cwd)) {
@@ -371,7 +367,10 @@ export function captureClaudeTranscriptAnchor(options) {
         !isClaudeAgentIdleState(agent)) {
         return undefined;
     }
-    const claudeHome = path.resolve(options.claudeHome ?? defaultClaudeHome());
+    const claudeHome = resolveClaudeTranscriptHome({
+        claudeHome: options.claudeHome, configDir: agent.configDir
+    });
+    const configDir = agent.configDir ? { config_dir: claudeHome } : {};
     const projectsRoot = projectsRootPath(claudeHome);
     if (!isRealDirectory(projectsRoot)) {
         if (lstatOrUndefined(projectsRoot) !== undefined ||
@@ -380,6 +379,7 @@ export function captureClaudeTranscriptAnchor(options) {
         }
         return {
             schema_version: CLAUDE_TRANSCRIPT_ANCHOR_VERSION,
+            ...configDir,
             session_id: sessionId,
             cwd: path.resolve(cwd),
             pid,
@@ -395,6 +395,7 @@ export function captureClaudeTranscriptAnchor(options) {
     if (!located) {
         return {
             schema_version: CLAUDE_TRANSCRIPT_ANCHOR_VERSION,
+            ...configDir,
             session_id: sessionId,
             cwd: path.resolve(cwd),
             pid,
@@ -415,6 +416,7 @@ export function captureClaudeTranscriptAnchor(options) {
         }
         return {
             schema_version: CLAUDE_TRANSCRIPT_ANCHOR_VERSION,
+            ...configDir,
             session_id: sessionId,
             cwd: path.resolve(cwd),
             pid,
@@ -448,7 +450,11 @@ export function captureClaudeHumanStartedActiveTaskAnchor(options) {
         !isActiveClaudeAgentState(agent)) {
         return undefined;
     }
-    const projectsRoot = projectsRootPath(path.resolve(options.claudeHome ?? defaultClaudeHome()));
+    const claudeHome = resolveClaudeTranscriptHome({
+        claudeHome: options.claudeHome, configDir: agent.configDir
+    });
+    const configDir = agent.configDir ? { config_dir: claudeHome } : {};
+    const projectsRoot = projectsRootPath(claudeHome);
     if (!isRealDirectory(projectsRoot)) {
         return undefined;
     }
@@ -492,6 +498,7 @@ export function captureClaudeHumanStartedActiveTaskAnchor(options) {
         const fileId = transcriptFileId(sessionId, `${device}:${inode}`);
         const transcriptAnchor = {
             schema_version: CLAUDE_TRANSCRIPT_ANCHOR_VERSION,
+            ...configDir,
             session_id: sessionId,
             cwd: path.resolve(cwd),
             pid,
@@ -525,6 +532,7 @@ export function captureClaudeHumanStartedActiveTaskAnchor(options) {
         const base = {
             schema: "agent-knock-knock/claude-human-started-active-task-anchor",
             version: 1,
+            ...configDir,
             session_id: sessionId,
             cwd: path.resolve(cwd),
             pid,
@@ -555,7 +563,11 @@ export function observeClaudeHumanStartedActiveTask(options) {
         const anchor = validateClaudeHumanStartedActiveTaskAnchor(options.anchor);
         const checkpoint = claudeActiveTaskObservationCheckpoint(anchor, options);
         const resumeOffsetBytes = checkpoint.safe_resume_offset_bytes;
-        const projectsRoot = projectsRootPath(path.resolve(options.claudeHome ?? defaultClaudeHome()));
+        const projectsRoot = projectsRootPath(resolveClaudeTranscriptHome({
+            claudeHome: options.claudeHome,
+            anchoredConfigDir: anchor.config_dir,
+            configDir: exactInteractiveAgent(options.agentRows, anchor.pid)?.configDir
+        }));
         if (!isRealDirectory(projectsRoot)) {
             return claudeActiveTaskUnavailable("Claude transcript projects directory is unavailable");
         }
@@ -656,12 +668,14 @@ export function validateClaudeHumanStartedActiveTaskAnchor(value) {
         "schema", "version", "session_id", "cwd", "pid", "agent_started_at_ms",
         "captured_at", "relative_path", "device", "inode", "prompt_uuid",
         "request_hash", "claude_version", "transcript_file_id",
-        "turn_start_offset_bytes", "observed_end_offset_bytes", "anchor_fingerprint"
+        "turn_start_offset_bytes", "observed_end_offset_bytes", "anchor_fingerprint",
+        "config_dir"
     ]);
     if (Object.keys(value).some((key) => !allowedKeys.has(key))) {
         throw new Error("Claude human-started active-task anchor has unsupported fields");
     }
     const sessionId = uuidValue(value.session_id);
+    validatedClaudeConfigDir(value.config_dir);
     const promptUuid = uuidValue(value.prompt_uuid);
     const cwd = nonEmptyString(value.cwd);
     const pid = positiveInteger(value.pid);
@@ -721,6 +735,7 @@ export function validateClaudeHumanStartedActiveTaskAnchor(value) {
 function claudeTranscriptAnchorForHumanStartedTask(anchor) {
     return {
         schema_version: CLAUDE_TRANSCRIPT_ANCHOR_VERSION,
+        ...(anchor.config_dir ? { config_dir: anchor.config_dir } : {}),
         session_id: anchor.session_id,
         cwd: anchor.cwd,
         pid: anchor.pid,
@@ -951,7 +966,7 @@ function advanceClaudeHumanStartedActiveTaskCheckpoint(anchor, checkpoint, recor
             lastRecordUuid = recordUuid;
         }
         if (hasUnresolvedBackgroundWork(record) ||
-            record.subtype === "stop_hook_summary") {
+            hasBlockingStopSummary(record)) {
             throw new Error("Claude anchored task acquired unsupported background or stop-hook work");
         }
         advanceClaudeCheckpointToolState(record, recordUuid, unresolvedToolUses);
@@ -1473,7 +1488,12 @@ function readClaudeTranscriptTurnSnapshot(request, options, requiredAgentStatus,
             return unavailable(`the exact Claude process is ${agent.status}, not ${requiredAgentStatus}`);
         }
     }
-    const projectsRoot = projectsRootPath(path.resolve(options.claudeHome ?? defaultClaudeHome()));
+    const projectsRoot = projectsRootPath(resolveClaudeTranscriptHome({
+        claudeHome: options.claudeHome,
+        anchoredConfigDir: anchor.config_dir,
+        configDir: readMode === "durable_fallback" ? undefined
+            : exactInteractiveAgent(options.agentRows, anchor.pid)?.configDir
+    }));
     if (!isRealDirectory(projectsRoot)) {
         return unavailable("Claude transcript projects directory is unavailable");
     }
@@ -1915,7 +1935,7 @@ function pendingApprovalEvidence(snapshot, promptUuid, lastDescendant, pending)
     if (!claudeVersion) {
         throw new Error("Claude pending Bash tool use has no compatible version");
     }
-    if (!isCompatiblePendingApprovalClaudeVersion(claudeVersion)) {
+    if (!isCompatibleClaudeVersion(claudeVersion)) {
         return undefined;
     }
     const commandSha256 = sha256Hex(command);
@@ -1975,6 +1995,7 @@ function transcriptAnchorFromContext(context) {
     const device = nonEmptyString(value.device);
     const inode = nonEmptyString(value.inode);
     const fileExisted = value.file_existed;
+    const configDir = validatedClaudeConfigDir(value.config_dir);
     if (schemaVersion !== CLAUDE_TRANSCRIPT_ANCHOR_VERSION ||
         !sessionId ||
         !cwd ||
@@ -1992,6 +2013,7 @@ function transcriptAnchorFromContext(context) {
     }
     return {
         schema_version: CLAUDE_TRANSCRIPT_ANCHOR_VERSION,
+        ...(configDir ? { config_dir: configDir } : {}),
         session_id: sessionId,
         cwd,
         pid,
@@ -2371,30 +2393,9 @@ function isCompatibleClaudeVersion(value) {
     if (!match) {
         return false;
     }
-    const parsed = match.slice(1).map(Number);
-    if (!parsed.every(Number.isSafeInteger)) {
-        return false;
-    }
-    for (let index = 0; index < parsed.length; index += 1) {
-        if (parsed[index] !== MINIMUM_CLAUDE_TRANSCRIPT_VERSION[index]) {
-            return parsed[index] > MINIMUM_CLAUDE_TRANSCRIPT_VERSION[index];
-        }
-    }
-    return true;
-}
-function isCompatiblePendingApprovalClaudeVersion(value) {
-    const version = nonEmptyString(value);
-    const match = version === undefined
-        ? undefined
-        : CLAUDE_TRANSCRIPT_VERSION_PATTERN.exec(version);
-    if (!match) {
-        return false;
-    }
-    const [major, minor, patch] = match.slice(1).map(Number);
-    return major === MINIMUM_CLAUDE_TRANSCRIPT_VERSION[0] &&
-        minor === MINIMUM_CLAUDE_TRANSCRIPT_VERSION[1] &&
-        Number.isSafeInteger(patch) &&
-        patch >= MINIMUM_CLAUDE_TRANSCRIPT_VERSION[2];
+    // The version binds evidence; the actual record shape and task chain prove
+    // compatibility. A release number alone must not reject an otherwise valid turn.
+    return match.slice(1).map(Number).every(Number.isSafeInteger);
 }
 function assertSameClaudeVersion(...records) {
     const versions = new Set(records.map((record) => nonEmptyString(record.version)));
@@ -2466,31 +2467,12 @@ function exactRequestFingerprint(value) {
     const text = String(value ?? "");
     return text ? createHash("sha256").update(text).digest("hex") : undefined;
 }
-export function claudeTranscriptAnchorFingerprint(anchor) {
-    return sha256Hex(JSON.stringify({
-        schema: "agent-knock-knock/claude-transcript-acceptance-anchor",
-        version: 1,
-        session_id: anchor.session_id,
-        cwd: anchor.cwd,
-        pid: anchor.pid,
-        agent_started_at_ms: anchor.agent_started_at_ms,
-        captured_at: anchor.captured_at,
-        relative_path: anchor.relative_path,
-        offset_bytes: anchor.offset_bytes,
-        file_existed: anchor.file_existed,
-        device: anchor.device ?? null,
-        inode: anchor.inode ?? null
-    }));
-}
 function exactPromptText(value) {
     const text = String(value ?? "")
         .replace(/\r\n/gu, "\n")
         .replace(/[\r\n]+$/u, "");
     return text.length > 0 ? text : undefined;
 }
-function transcriptFileId(sessionId, fileIdentity) {
-    return sha256Hex(`${sessionId}\0${fileIdentity}`).slice(0, 24);
-}
 function sha256Hex(value) {
     return createHash("sha256").update(value).digest("hex");
 }