fix(codex): hash dynamic tool fingerprints

vincentkoc · vincentkoc · commit 305174845f38 · 2026-07-11T17:41:01.000-07:00
diff --git a/extensions/codex/src/app-server/thread-lifecycle.test.ts b/extensions/codex/src/app-server/thread-lifecycle.test.ts
@@ -17,7 +17,9 @@ import {
   buildTurnStartParams,
   buildThreadResumeParams,
   buildThreadStartParams,
+  areCodexDynamicToolFingerprintsCompatible,
   codexDynamicToolsFingerprint,
+  codexLegacyDynamicToolsFingerprint,
   formatCodexThreadLifecycleTimingSummary,
   resolveCodexAppServerThreadModelSelection,
   resolveReasoningEffort,
@@ -363,6 +365,36 @@ describe("Codex app-server native code mode config", () => {
     expect(searchableFingerprint).not.toBe(directFingerprint);
   });
 
+  it("keeps hashed dynamic tool fingerprints compatible with legacy JSON bindings", () => {
+    const tools = [
+      {
+        type: "function" as const,
+        name: "message",
+        description: "Send a visible message",
+        inputSchema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            text: { type: "string" },
+          },
+          required: ["text"],
+        },
+      },
+    ];
+    const hashed = codexDynamicToolsFingerprint(tools);
+    const legacy = codexLegacyDynamicToolsFingerprint(tools);
+
+    expect(hashed).toMatch(/^sha256:/);
+    expect(legacy).toContain('"name":"message"');
+    expect(
+      areCodexDynamicToolFingerprintsCompatible({
+        previous: legacy,
+        next: hashed,
+        nextLegacy: legacy,
+      }),
+    ).toBe(true);
+  });
+
   it("keeps OpenClaw skill catalogs out of developer instructions", () => {
     const params = createAttemptParams({ provider: "openai" });
     params.skillsSnapshot = {
diff --git a/extensions/codex/src/app-server/thread-lifecycle.ts b/extensions/codex/src/app-server/thread-lifecycle.ts
@@ -1,4 +1,5 @@
 // Codex plugin module implements thread lifecycle behavior.
+import * as crypto from "node:crypto";
 import {
   buildSkillWorkshopPromptSection,
   embeddedAgentLog,
@@ -349,8 +350,12 @@ export async function startOrResumeThread(params: {
       ...params.timing,
       enabled: params.timing?.enabled ?? isCodexAppServerProfilerEnabled(params.params.config),
     });
+    const legacyDynamicToolsFingerprint = lifecycleTiming.measureSync(
+      "legacy-dynamic-tools-fingerprint",
+      () => legacyFingerprintDynamicTools(params.dynamicTools),
+    );
     const dynamicToolsFingerprint = lifecycleTiming.measureSync("dynamic-tools-fingerprint", () =>
-      fingerprintDynamicTools(params.dynamicTools),
+      hashDynamicToolFingerprint(legacyDynamicToolsFingerprint),
     );
     const dynamicToolsContainDeferred = flattenCodexDynamicToolFunctions(params.dynamicTools).some(
       (tool) => tool.deferLoading === true,
@@ -674,11 +679,12 @@ export async function startOrResumeThread(params: {
         !areDynamicToolFingerprintsCompatible(
           binding.dynamicToolsFingerprint,
           dynamicToolsFingerprint,
+          legacyDynamicToolsFingerprint,
         )
       ) {
         preserveExistingBinding = shouldStartTransientNoToolThread({
           previous: binding.dynamicToolsFingerprint,
-          next: dynamicToolsFingerprint,
+          nextHasDynamicTools: params.dynamicTools.length > 0,
         });
         if (preserveExistingBinding) {
           embeddedAgentLog.debug(
@@ -1663,19 +1669,32 @@ export function codexDynamicToolsFingerprint(dynamicTools: CodexDynamicToolSpec[
   return fingerprintDynamicTools(dynamicTools);
 }
 
+export function codexLegacyDynamicToolsFingerprint(dynamicTools: CodexDynamicToolSpec[]): string {
+  return legacyFingerprintDynamicTools(dynamicTools);
+}
+
 export function areCodexDynamicToolFingerprintsCompatible(params: {
   previous?: string;
   next: string;
+  nextLegacy?: string;
 }): boolean {
-  return areDynamicToolFingerprintsCompatible(params.previous, params.next);
+  return areDynamicToolFingerprintsCompatible(params.previous, params.next, params.nextLegacy);
 }
 
 function fingerprintDynamicTools(dynamicTools: CodexDynamicToolSpec[]): string {
+  return hashDynamicToolFingerprint(legacyFingerprintDynamicTools(dynamicTools));
+}
+
+function legacyFingerprintDynamicTools(dynamicTools: CodexDynamicToolSpec[]): string {
   return JSON.stringify(
     dynamicTools.map(fingerprintDynamicToolSpec).toSorted(compareJsonFingerprint),
   );
 }
 
+function hashDynamicToolFingerprint(canonical: string): string {
+  return "sha256:" + crypto.createHash("sha256").update(canonical).digest("hex");
+}
+
 function fingerprintUserMcpServersConfigPatch(
   configPatch: JsonObject | undefined,
 ): string | undefined {
@@ -1740,20 +1759,34 @@ function readActiveCodexTurnIds(thread: unknown): string[] {
     .filter((turnId) => turnId.trim().length > 0);
 }
 
-const EMPTY_DYNAMIC_TOOLS_FINGERPRINT = JSON.stringify([]);
+const LEGACY_EMPTY_DYNAMIC_TOOLS_FINGERPRINT = legacyFingerprintDynamicTools([]);
+const EMPTY_DYNAMIC_TOOLS_FINGERPRINT = hashDynamicToolFingerprint(
+  LEGACY_EMPTY_DYNAMIC_TOOLS_FINGERPRINT,
+);
 
-function areDynamicToolFingerprintsCompatible(previous: string | undefined, next: string): boolean {
-  return !previous || previous === next;
+function areDynamicToolFingerprintsCompatible(
+  previous: string | undefined,
+  next: string,
+  nextLegacy?: string,
+): boolean {
+  return !previous || previous === next || previous === nextLegacy;
 }
 
 function shouldStartTransientNoToolThread(params: {
   previous: string | undefined;
-  next: string;
+  nextHasDynamicTools: boolean;
 }): boolean {
   return Boolean(
     params.previous &&
-    params.previous !== EMPTY_DYNAMIC_TOOLS_FINGERPRINT &&
-    params.next === EMPTY_DYNAMIC_TOOLS_FINGERPRINT,
+    !isEmptyDynamicToolsFingerprint(params.previous) &&
+    !params.nextHasDynamicTools,
+  );
+}
+
+function isEmptyDynamicToolsFingerprint(fingerprint: string): boolean {
+  return (
+    fingerprint === EMPTY_DYNAMIC_TOOLS_FINGERPRINT ||
+    fingerprint === LEGACY_EMPTY_DYNAMIC_TOOLS_FINGERPRINT
   );
 }
 
