fix(hooks): deduplicate multi-scope invocations

__tests__/hooks/handler.test.ts

@@ -49,6 +49,10 @@ vi.mock("../../src/hooks/hook-logger", () => ({
   hookLogError: vi.fn(),
 }));
 
+vi.mock("../../src/hooks/hook-invocation-dedup", () => ({
+  claimHookInvocation: vi.fn(() => Promise.resolve({ role: "independent" })),
+}));
+
 describe("hooks/handler", () => {
   let stderrSpy: ReturnType<typeof vi.spyOn>;
   let stdoutSpy: ReturnType<typeof vi.spyOn>;
@@ -1251,6 +1255,28 @@ describe("hooks/handler", () => {
     );
   });
 
+  it("replays a duplicate decision without evaluating or persisting again", async () => {
+    const { claimHookInvocation } = await import("../../src/hooks/hook-invocation-dedup");
+    vi.mocked(claimHookInvocation).mockResolvedValueOnce({
+      role: "duplicate",
+      response: { exitCode: 2, stdout: "", stderr: "blocked once" },
+    });
+    mockStdin(JSON.stringify({
+      session_id: "session-1",
+      tool_use_id: "tool-1",
+      tool_name: "Bash",
+    }));
+    const { evaluatePolicies } = await import("../../src/hooks/policy-evaluator");
+    const { persistHookActivity } = await import("../../src/hooks/hook-activity-store");
+
+    const exitCode = await handleHookEvent("PreToolUse");
+
+    expect(exitCode).toBe(2);
+    expect(stderrSpy).toHaveBeenCalledWith("blocked once");
+    expect(evaluatePolicies).not.toHaveBeenCalled();
+    expect(persistHookActivity).not.toHaveBeenCalled();
+  });
+
   it("persists instruct decision as 'instruct' in activity store", async () => {
     const { evaluatePolicies } = await import("../../src/hooks/policy-evaluator");
     vi.mocked(evaluatePolicies).mockResolvedValueOnce({

__tests__/hooks/hook-invocation-dedup.test.ts

@@ -0,0 +1,91 @@
+// @vitest-environment node
+import { afterEach, describe, expect, it } from "vitest";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  claimHookInvocation,
+  setHookInvocationDedupDirForTests,
+} from "../../src/hooks/hook-invocation-dedup";
+
+describe("hook invocation deduplication", () => {
+  const tempDirs: string[] = [];
+
+  async function useTempDir(): Promise<void> {
+    const dir = await mkdtemp(join(tmpdir(), "failproofai-hook-dedup-"));
+    tempDirs.push(dir);
+    setHookInvocationDedupDirForTests(dir);
+  }
+
+  afterEach(async () => {
+    await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+  });
+
+  it("elects one owner and replays its response to a duplicate process", async () => {
+    await useTempDir();
+    const payload = { session_id: "session-1", tool_use_id: "tool-1" };
+    const owner = await claimHookInvocation("PreToolUse", "claude", payload);
+    expect(owner.role).toBe("owner");
+    if (owner.role !== "owner") throw new Error("expected owner claim");
+
+    const duplicatePromise = claimHookInvocation("PreToolUse", "claude", payload);
+    await owner.complete({ exitCode: 2, stdout: "", stderr: "blocked" });
+    const duplicate = await duplicatePromise;
+
+    expect(duplicate).toEqual({
+      role: "duplicate",
+      response: { exitCode: 2, stdout: "", stderr: "blocked" },
+    });
+    await expect(claimHookInvocation("PreToolUse", "claude", payload)).resolves.toEqual({
+      role: "duplicate",
+      response: { exitCode: 2, stdout: "", stderr: "blocked" },
+    });
+  });
+
+  it("does not combine different tool uses or hook events", async () => {
+    await useTempDir();
+    const first = await claimHookInvocation("PreToolUse", "claude", {
+      session_id: "session-1",
+      tool_use_id: "tool-1",
+    });
+    const differentTool = await claimHookInvocation("PreToolUse", "claude", {
+      session_id: "session-1",
+      tool_use_id: "tool-2",
+    });
+    const differentEvent = await claimHookInvocation("PostToolUse", "claude", {
+      session_id: "session-1",
+      tool_use_id: "tool-1",
+    });
+
+    expect(first.role).toBe("owner");
+    expect(differentTool.role).toBe("owner");
+    expect(differentEvent.role).toBe("owner");
+    if (first.role === "owner") await first.release();
+    if (differentTool.role === "owner") await differentTool.release();
+    if (differentEvent.role === "owner") await differentEvent.release();
+  });
+
+  it("lets another process take ownership when the first exits before publishing", async () => {
+    await useTempDir();
+    const payload = { session_id: "session-1", tool_use_id: "tool-1" };
+    const first = await claimHookInvocation("PreToolUse", "claude", payload);
+    expect(first.role).toBe("owner");
+    if (first.role !== "owner") throw new Error("expected owner claim");
+    await first.release();
+
+    const retry = await claimHookInvocation("PreToolUse", "claude", payload);
+    expect(retry.role).toBe("owner");
+    if (retry.role === "owner") await retry.release();
+  });
+
+  it("only deduplicates Claude payloads with stable invocation identifiers", async () => {
+    await useTempDir();
+    await expect(claimHookInvocation("PreToolUse", "codex", {
+      session_id: "session-1",
+      tool_use_id: "tool-1",
+    })).resolves.toEqual({ role: "independent" });
+    await expect(claimHookInvocation("PreToolUse", "claude", {
+      session_id: "session-1",
+    })).resolves.toEqual({ role: "independent" });
+  });
+});

src/hooks/handler.ts

@@ -39,6 +39,7 @@ import { resolvePermissionMode } from "./resolve-permission-mode";
 import { resolveTranscriptPath } from "./resolve-transcript-path";
 import { getInstanceId } from "../../lib/telemetry-id";
 import { hookLogInfo, hookLogWarn } from "./hook-logger";
+import { claimHookInvocation } from "./hook-invocation-dedup";
 
 /**
  * Canonicalize an event name to PascalCase. Codex sends snake_case event names
@@ -92,6 +93,7 @@ export async function handleHookEvent(
   cli: IntegrationType = "claude",
 ): Promise<number> {
   const startTime = performance.now();
+  let invocationClaim: Awaited<ReturnType<typeof claimHookInvocation>> | undefined;
   try {
 
     // Read stdin payload (Claude passes JSON)
@@ -197,6 +199,14 @@ export async function handleHookEvent(
       }
     }
 
+    invocationClaim = await claimHookInvocation(eventType, cli, parsed);
+    if (invocationClaim.role === "duplicate") {
+      if (invocationClaim.response.stdout) process.stdout.write(invocationClaim.response.stdout);
+      if (invocationClaim.response.stderr) process.stderr.write(invocationClaim.response.stderr);
+      hookLogInfo(`duplicate invocation replayed event=${eventType} cli=${cli}`);
+      return invocationClaim.response.exitCode;
+    }
+
     // Canonicalize event name (Codex sends snake_case; internals expect PascalCase)
     const canonicalEventType = canonicalizeEventType(eventType, cli);
 
@@ -311,6 +321,13 @@ export async function handleHookEvent(
 
     // Evaluate policies (use canonical PascalCase event type)
     const result = await evaluatePolicies(canonicalEventType, parsed, session, config);
+    if (invocationClaim.role === "owner") {
+      await invocationClaim.complete({
+        exitCode: result.exitCode,
+        stdout: result.stdout,
+        stderr: result.stderr,
+      });
+    }
     const durationMs = Math.round(performance.now() - startTime);
     hookLogInfo(`result=${result.decision} policy=${result.policyName ?? "none"} duration=${durationMs}ms`);
 
@@ -376,6 +393,7 @@ export async function handleHookEvent(
     }
     return result.exitCode;
   } finally {
+    if (invocationClaim?.role === "owner") await invocationClaim.release();
     // Await any un-awaited (`void trackHookEvent(...)`) events fired during
     // this invocation. bin/failproofai.mjs calls process.exit() the moment we
     // return OR throw, which would otherwise drop in-flight POSTs — notably on

src/hooks/hook-invocation-dedup.ts

@@ -0,0 +1,149 @@
+/**
+ * Cross-process deduplication for Claude hooks installed in multiple scopes.
+ *
+ * Claude starts one hook process per matching user/project/local registration.
+ * Those processes receive the same session + tool-use identifiers. An exclusive
+ * lock elects one process to evaluate policies; the others wait briefly and
+ * replay its response without duplicating activity or telemetry.
+ */
+import { createHash } from "node:crypto";
+import { mkdir, open, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { IntegrationType } from "./types";
+
+const RESULT_TTL_MS = 5 * 60_000;
+const WAIT_TIMEOUT_MS = 12_000;
+const POLL_INTERVAL_MS = 10;
+
+let dedupDir = join(homedir(), ".failproofai", "cache", "hook-invocations");
+
+export interface HookInvocationResponse {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export type HookInvocationClaim =
+  | { role: "owner"; complete: (response: HookInvocationResponse) => Promise<void>; release: () => Promise<void> }
+  | { role: "duplicate"; response: HookInvocationResponse }
+  | { role: "independent" };
+
+function invocationKey(
+  eventType: string,
+  cli: IntegrationType,
+  payload: Record<string, unknown>,
+): string | null {
+  if (cli !== "claude") return null;
+  const sessionId = payload.session_id;
+  const toolUseId = payload.tool_use_id;
+  if (typeof sessionId !== "string" || typeof toolUseId !== "string") return null;
+  return createHash("sha256").update(`${cli}\0${eventType}\0${sessionId}\0${toolUseId}`).digest("hex");
+}
+
+async function removeOldEntries(): Promise<void> {
+  try {
+    const names = await readdir(dedupDir);
+    const now = Date.now();
+    await Promise.all(names.map(async (name) => {
+      const path = join(dedupDir, name);
+      try {
+        if (now - (await stat(path)).mtimeMs > RESULT_TTL_MS) await unlink(path);
+      } catch {
+        // Another hook process may have removed it first.
+      }
+    }));
+  } catch {
+    // Cleanup is best-effort and must never delay or block policy evaluation.
+  }
+}
+
+async function readResponse(path: string): Promise<HookInvocationResponse | null> {
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8")) as Partial<HookInvocationResponse>;
+    if (
+      typeof parsed.exitCode === "number"
+      && typeof parsed.stdout === "string"
+      && typeof parsed.stderr === "string"
+    ) {
+      return parsed as HookInvocationResponse;
+    }
+  } catch {
+    // The owner has not published its response yet.
+  }
+  return null;
+}
+
+async function readFreshResponse(path: string): Promise<HookInvocationResponse | null> {
+  try {
+    if (Date.now() - (await stat(path)).mtimeMs > RESULT_TTL_MS) return null;
+  } catch {
+    return null;
+  }
+  return readResponse(path);
+}
+
+export async function claimHookInvocation(
+  eventType: string,
+  cli: IntegrationType,
+  payload: Record<string, unknown>,
+): Promise<HookInvocationClaim> {
+  const key = invocationKey(eventType, cli, payload);
+  if (!key) return { role: "independent" };
+
+  try {
+    await mkdir(dedupDir, { recursive: true });
+    void removeOldEntries();
+    const lockPath = join(dedupDir, `${key}.lock`);
+    const resultPath = join(dedupDir, `${key}.json`);
+    const existingResponse = await readFreshResponse(resultPath);
+    if (existingResponse) return { role: "duplicate", response: existingResponse };
+
+    try {
+      const handle = await open(lockPath, "wx");
+      await handle.close();
+      const racedResponse = await readFreshResponse(resultPath);
+      if (racedResponse) {
+        try { await unlink(lockPath); } catch { /* best-effort */ }
+        return { role: "duplicate", response: racedResponse };
+      }
+      let completed = false;
+      return {
+        role: "owner",
+        complete: async (response) => {
+          try {
+            const tmpPath = `${resultPath}.${process.pid}.tmp`;
+            await writeFile(tmpPath, JSON.stringify(response), "utf8");
+            await rename(tmpPath, resultPath);
+            completed = true;
+          } catch {
+            // Publishing is best-effort; the owner must still return its policy result.
+          } finally {
+            try { await unlink(lockPath); } catch { /* best-effort */ }
+          }
+        },
+        release: async () => {
+          if (!completed) {
+            try { await unlink(lockPath); } catch { /* best-effort */ }
+          }
+        },
+      };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") return { role: "independent" };
+    }
+
+    const deadline = Date.now() + WAIT_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+      const response = await readResponse(resultPath);
+      if (response) return { role: "duplicate", response };
+      await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    }
+  } catch {
+    // Deduplication is an optimization. Fail open into normal policy evaluation.
+  }
+  return { role: "independent" };
+}
+
+export function setHookInvocationDedupDirForTests(path: string): void {
+  dedupDir = path;
+}