From 223feb0048a81ebd545b1be0b211062e8dc8a62e Mon Sep 17 00:00:00 2001
From: Nikita Agarwal <niki.darj@gmail.com>
Date: Sun, 3 May 2026 11:38:32 -0700
Subject: [PATCH 1/3] feat: add Gemini CLI integration to hooks system

---
 .gemini/settings.json                    | 147 ++++++++++++++++
 __tests__/hooks/handler.test.ts          | 191 ++++++++++++++++++++
 __tests__/hooks/integrations.test.ts     | 215 ++++++++++++++++++++++-
 __tests__/hooks/policy-evaluator.test.ts | 189 ++++++++++++++++++++
 bin/failproofai.mjs                      |  34 ++--
 src/hooks/builtin-policies.ts            |  12 +-
 src/hooks/handler.ts                     |  43 ++++-
 src/hooks/install-prompt.ts              |   4 +-
 src/hooks/integrations.ts                | 160 +++++++++++++++++
 src/hooks/policy-evaluator.ts            | 133 ++++++++++++++
 src/hooks/resolve-permission-mode.ts     |   7 +-
 src/hooks/types.ts                       | 117 +++++++++++-
 12 files changed, 1223 insertions(+), 29 deletions(-)
 create mode 100644 .gemini/settings.json

diff --git a/.gemini/settings.json b/.gemini/settings.json
new file mode 100644
index 00000000..781e6d5c
--- /dev/null
+++ b/.gemini/settings.json
@@ -0,0 +1,147 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun $GEMINI_PROJECT_DIR/bin/failproofai.mjs --hook SessionStart --cli gemini",
+            "timeout": 60000,
+            "__failproofai_hook__": true
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun $GEMINI_PROJECT_DIR/bin/failproofai.mjs --hook SessionEnd --cli gemini",
+            "timeout": 60000,
+            "__failproofai_hook__": true
+          }
+        ]
+      }
+    ],
+    "BeforeAgent": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun $GEMINI_PROJECT_DIR/bin/failproofai.mjs --hook BeforeAgent --cli gemini",
+            "timeout": 60000,
+            "__failproofai_hook__": true
+          }
+        ]
+      }
+    ],
+    "AfterAgent": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun $GEMINI_PROJECT_DIR/bin/failproofai.mjs --hook AfterAgent --cli gemini",
+            "timeout": 60000,
+            "__failproofai_hook__": true
+          }
+        ]
+      }
+    ],
+    "BeforeModel": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun $GEMINI_PROJECT_DIR/bin/failproofai.mjs --hook BeforeModel --cli gemini",
+            "timeout": 60000,
+            "__failproofai_hook__": true
+          }
+        ]
+      }
+    ],
+    "AfterModel": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun $GEMINI_PROJECT_DIR/bin/failproofai.mjs --hook AfterModel --cli gemini",
+            "timeout": 60000,
+            "__failproofai_hook__": true
+          }
+        ]
+      }
+    ],
+    "BeforeToolSelection": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun $GEMINI_PROJECT_DIR/bin/failproofai.mjs --hook BeforeToolSelection --cli gemini",
+            "timeout": 60000,
+            "__failproofai_hook__": true
+          }
+        ]
+      }
+    ],
+    "BeforeTool": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun $GEMINI_PROJECT_DIR/bin/failproofai.mjs --hook BeforeTool --cli gemini",
+            "timeout": 60000,
+            "__failproofai_hook__": true
+          }
+        ]
+      }
+    ],
+    "AfterTool": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun $GEMINI_PROJECT_DIR/bin/failproofai.mjs --hook AfterTool --cli gemini",
+            "timeout": 60000,
+            "__failproofai_hook__": true
+          }
+        ]
+      }
+    ],
+    "PreCompress": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun $GEMINI_PROJECT_DIR/bin/failproofai.mjs --hook PreCompress --cli gemini",
+            "timeout": 60000,
+            "__failproofai_hook__": true
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun $GEMINI_PROJECT_DIR/bin/failproofai.mjs --hook Notification --cli gemini",
+            "timeout": 60000,
+            "__failproofai_hook__": true
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/__tests__/hooks/handler.test.ts b/__tests__/hooks/handler.test.ts
index ec4e086e..996cbb6d 100644
--- a/__tests__/hooks/handler.test.ts
+++ b/__tests__/hooks/handler.test.ts
@@ -447,6 +447,197 @@ describe("hooks/handler", () => {
       );
     });
 
+    it("canonicalizes Gemini BeforeTool → PreToolUse before evaluating", async () => {
+      const { evaluatePolicies } = await import("../../src/hooks/policy-evaluator");
+      vi.mocked(evaluatePolicies).mockResolvedValueOnce({
+        exitCode: 0,
+        stdout: "",
+        stderr: "",
+        policyName: null,
+        reason: null,
+        decision: "allow",
+      });
+      mockStdin(JSON.stringify({ tool_name: "run_shell_command", hook_event_name: "BeforeTool" }));
+      const { persistHookActivity } = await import("../../src/hooks/hook-activity-store");
+
+      await handleHookEvent("BeforeTool", "gemini");
+
+      expect(evaluatePolicies).toHaveBeenCalledWith(
+        "PreToolUse",
+        expect.any(Object),
+        expect.any(Object),
+        expect.any(Object),
+      );
+      expect(persistHookActivity).toHaveBeenCalledWith(
+        expect.objectContaining({ integration: "gemini", eventType: "PreToolUse" }),
+      );
+    });
+
+    it("canonicalizes Gemini snake_case tool name run_shell_command → Bash before evaluating", async () => {
+      const { evaluatePolicies } = await import("../../src/hooks/policy-evaluator");
+      vi.mocked(evaluatePolicies).mockResolvedValueOnce({
+        exitCode: 0,
+        stdout: "",
+        stderr: "",
+        policyName: null,
+        reason: null,
+        decision: "allow",
+      });
+      mockStdin(JSON.stringify({ tool_name: "run_shell_command", hook_event_name: "BeforeTool" }));
+      const { persistHookActivity } = await import("../../src/hooks/hook-activity-store");
+
+      await handleHookEvent("BeforeTool", "gemini");
+
+      // The mutated payload passed to evaluatePolicies should carry the canonicalized tool_name
+      expect(evaluatePolicies).toHaveBeenCalledWith(
+        "PreToolUse",
+        expect.objectContaining({ tool_name: "Bash" }),
+        expect.any(Object),
+        expect.any(Object),
+      );
+      // Activity store should also see canonicalized toolName=Bash, NOT raw run_shell_command
+      expect(persistHookActivity).toHaveBeenCalledWith(
+        expect.objectContaining({ integration: "gemini", toolName: "Bash" }),
+      );
+    });
+
+    it("canonicalizes every Gemini tool name in GEMINI_TOOL_MAP", async () => {
+      const { evaluatePolicies } = await import("../../src/hooks/policy-evaluator");
+      const cases: Array<[string, string]> = [
+        ["run_shell_command", "Bash"],
+        ["read_file", "Read"],
+        ["read_many_files", "Read"],
+        ["write_file", "Write"],
+        ["replace", "Edit"],
+        ["glob", "Glob"],
+        ["grep_search", "Grep"],
+        ["list_directory", "LS"],
+        ["web_fetch", "WebFetch"],
+        ["google_web_search", "WebSearch"],
+        ["write_todos", "TodoWrite"],
+        ["save_memory", "Memory"],
+        ["ask_user", "AskUser"],
+      ];
+      for (const [raw, canonical] of cases) {
+        vi.mocked(evaluatePolicies).mockResolvedValueOnce({
+          exitCode: 0, stdout: "", stderr: "", policyName: null, reason: null, decision: "allow",
+        });
+        mockStdin(JSON.stringify({ tool_name: raw, hook_event_name: "BeforeTool" }));
+        await handleHookEvent("BeforeTool", "gemini");
+        expect(evaluatePolicies).toHaveBeenLastCalledWith(
+          "PreToolUse",
+          expect.objectContaining({ tool_name: canonical }),
+          expect.any(Object),
+          expect.any(Object),
+        );
+      }
+    });
+
+    it("passes through unknown Gemini tool names (MCP, extensions) unchanged", async () => {
+      const { evaluatePolicies } = await import("../../src/hooks/policy-evaluator");
+      vi.mocked(evaluatePolicies).mockResolvedValueOnce({
+        exitCode: 0, stdout: "", stderr: "", policyName: null, reason: null, decision: "allow",
+      });
+      mockStdin(JSON.stringify({ tool_name: "mcp_github_create_issue", hook_event_name: "BeforeTool" }));
+
+      await handleHookEvent("BeforeTool", "gemini");
+
+      // Unknown tool names are NOT in GEMINI_TOOL_MAP — must pass through unchanged so MCP tools aren't lost
+      expect(evaluatePolicies).toHaveBeenCalledWith(
+        "PreToolUse",
+        expect.objectContaining({ tool_name: "mcp_github_create_issue" }),
+        expect.any(Object),
+        expect.any(Object),
+      );
+    });
+
+    it("does NOT canonicalize tool names when cli=claude (other CLIs unaffected)", async () => {
+      const { evaluatePolicies } = await import("../../src/hooks/policy-evaluator");
+      vi.mocked(evaluatePolicies).mockResolvedValueOnce({
+        exitCode: 0, stdout: "", stderr: "", policyName: null, reason: null, decision: "allow",
+      });
+      // A Claude session that somehow has a Gemini-shaped tool name should NOT be remapped.
+      mockStdin(JSON.stringify({ tool_name: "run_shell_command", hook_event_name: "PreToolUse" }));
+
+      await handleHookEvent("PreToolUse", "claude");
+
+      expect(evaluatePolicies).toHaveBeenCalledWith(
+        "PreToolUse",
+        expect.objectContaining({ tool_name: "run_shell_command" }),
+        expect.any(Object),
+        expect.any(Object),
+      );
+    });
+
+    it("canonicalizes all 11 Gemini events to canonical names (BeforeAgent → UserPromptSubmit, etc.)", async () => {
+      const { evaluatePolicies } = await import("../../src/hooks/policy-evaluator");
+      const cases: Array<[string, string]> = [
+        ["SessionStart", "SessionStart"],
+        ["SessionEnd", "SessionEnd"],
+        ["BeforeAgent", "UserPromptSubmit"],
+        ["AfterAgent", "Stop"],
+        ["BeforeTool", "PreToolUse"],
+        ["AfterTool", "PostToolUse"],
+        ["PreCompress", "PreCompact"],
+        ["Notification", "Notification"],
+        // Gemini-only events with no Claude canonical — passthrough.
+        ["BeforeModel", "BeforeModel"],
+        ["AfterModel", "AfterModel"],
+        ["BeforeToolSelection", "BeforeToolSelection"],
+      ];
+      for (const [raw, canonical] of cases) {
+        vi.mocked(evaluatePolicies).mockResolvedValueOnce({
+          exitCode: 0, stdout: "", stderr: "", policyName: null, reason: null, decision: "allow",
+        });
+        mockStdin(JSON.stringify({ hook_event_name: raw }));
+        await handleHookEvent(raw, "gemini");
+        expect(evaluatePolicies).toHaveBeenLastCalledWith(
+          canonical,
+          expect.any(Object),
+          expect.any(Object),
+          expect.any(Object),
+        );
+      }
+    });
+
+    it("tags telemetry with cli=gemini and canonicalized tool_name=Bash when invoked with --cli gemini", async () => {
+      const { evaluatePolicies } = await import("../../src/hooks/policy-evaluator");
+      vi.mocked(evaluatePolicies).mockResolvedValueOnce({
+        exitCode: 0,
+        stdout: '{"decision":"deny","reason":"sudo blocked"}',
+        stderr: "",
+        policyName: "block-sudo",
+        reason: "sudo blocked",
+        decision: "deny",
+      });
+      mockStdin(JSON.stringify({ tool_name: "run_shell_command", hook_event_name: "BeforeTool" }));
+      const { trackHookEvent } = await import("../../src/hooks/hook-telemetry");
+
+      await handleHookEvent("BeforeTool", "gemini");
+
+      // Telemetry should see the canonicalized tool name (Bash, not run_shell_command)
+      expect(trackHookEvent).toHaveBeenCalledWith(
+        "test-instance-id",
+        "hook_policy_triggered",
+        expect.objectContaining({ cli: "gemini", event_type: "PreToolUse", tool_name: "Bash" }),
+      );
+    });
+
+    it("tags activity store entry with integration=gemini and canonicalized eventType for Gemini hook fires", async () => {
+      const { evaluatePolicies } = await import("../../src/hooks/policy-evaluator");
+      vi.mocked(evaluatePolicies).mockResolvedValueOnce({
+        exitCode: 0, stdout: "", stderr: "", policyName: null, reason: null, decision: "allow",
+      });
+      mockStdin(JSON.stringify({ tool_name: "read_file", hook_event_name: "BeforeTool" }));
+      const { persistHookActivity } = await import("../../src/hooks/hook-activity-store");
+
+      await handleHookEvent("BeforeTool", "gemini");
+
+      expect(persistHookActivity).toHaveBeenCalledWith(
+        expect.objectContaining({ integration: "gemini", eventType: "PreToolUse", toolName: "Read" }),
+      );
+    });
+
     it("fires telemetry with full payload for instruct decisions", async () => {
       const { evaluatePolicies } = await import("../../src/hooks/policy-evaluator");
       vi.mocked(evaluatePolicies).mockResolvedValueOnce({
diff --git a/__tests__/hooks/integrations.test.ts b/__tests__/hooks/integrations.test.ts
index 044bc705..fd4d36f1 100644
--- a/__tests__/hooks/integrations.test.ts
+++ b/__tests__/hooks/integrations.test.ts
@@ -20,6 +20,7 @@ import {
   cursor,
   opencode,
   pi,
+  gemini,
   getIntegration,
   listIntegrations,
 } from "../../src/hooks/integrations";
@@ -33,12 +34,16 @@ import {
   OPENCODE_EVENT_MAP,
   PI_HOOK_EVENT_TYPES,
   PI_EVENT_MAP,
+  GEMINI_HOOK_EVENT_TYPES,
+  GEMINI_EVENT_MAP,
+  GEMINI_TOOL_MAP,
   HOOK_EVENT_TYPES,
   FAILPROOFAI_HOOK_MARKER,
   type CodexHookEventType,
   type CursorHookEventType,
   type OpenCodeHookEventType,
   type PiHookEventType,
+  type GeminiHookEventType,
 } from "../../src/hooks/types";
 import { homedir } from "node:os";
 
@@ -62,9 +67,9 @@ afterEach(() => {
 });
 
 describe("integrations registry", () => {
-  it("listIntegrations returns claude, codex, copilot, cursor, opencode, and pi", () => {
+  it("listIntegrations returns claude, codex, copilot, cursor, opencode, pi, and gemini in declared order", () => {
     const ids = listIntegrations().map((i) => i.id);
-    expect(ids).toEqual(["claude", "codex", "copilot", "cursor", "opencode", "pi"]);
+    expect(ids).toEqual(["claude", "codex", "copilot", "cursor", "opencode", "pi", "gemini"]);
   });
 
   it("getIntegration('claude') returns claudeCode", () => {
@@ -91,6 +96,10 @@ describe("integrations registry", () => {
     expect(getIntegration("pi")).toBe(pi);
   });
 
+  it("getIntegration('gemini') returns gemini", () => {
+    expect(getIntegration("gemini")).toBe(gemini);
+  });
+
   it("getIntegration throws for unknown id", () => {
     // @ts-expect-error — testing error path
     expect(() => getIntegration("unknown-cli")).toThrow();
@@ -898,3 +907,205 @@ describe("PI_EVENT_MAP", () => {
     expect(PI_EVENT_MAP[sample]).toBe("PreToolUse");
   });
 });
+
+describe("Gemini CLI integration", () => {
+  it("getSettingsPath maps user → ~/.gemini/settings.json and project → <cwd>/.gemini/settings.json", () => {
+    expect(gemini.getSettingsPath("project", tempDir)).toBe(
+      resolve(tempDir, ".gemini", "settings.json"),
+    );
+    expect(gemini.getSettingsPath("user")).toMatch(/\.gemini\/settings\.json$/);
+  });
+
+  it("getSettingsPath('local') falls back to project (no gemini local scope)", () => {
+    expect(gemini.getSettingsPath("local", tempDir)).toBe(
+      resolve(tempDir, ".gemini", "settings.json"),
+    );
+  });
+
+  it("scopes are user|project (no local; system scope ignored)", () => {
+    expect(gemini.scopes).toEqual(["user", "project"]);
+    expect(gemini.scopes).not.toContain("local");
+  });
+
+  it("eventTypes are the 11 PascalCase Gemini events", () => {
+    expect(gemini.eventTypes).toEqual(GEMINI_HOOK_EVENT_TYPES);
+    expect(gemini.eventTypes).toContain("SessionStart");
+    expect(gemini.eventTypes).toContain("SessionEnd");
+    expect(gemini.eventTypes).toContain("BeforeAgent");
+    expect(gemini.eventTypes).toContain("AfterAgent");
+    expect(gemini.eventTypes).toContain("BeforeModel");
+    expect(gemini.eventTypes).toContain("AfterModel");
+    expect(gemini.eventTypes).toContain("BeforeToolSelection");
+    expect(gemini.eventTypes).toContain("BeforeTool");
+    expect(gemini.eventTypes).toContain("AfterTool");
+    expect(gemini.eventTypes).toContain("PreCompress");
+    expect(gemini.eventTypes).toContain("Notification");
+    expect(gemini.eventTypes).toHaveLength(11);
+  });
+
+  it("buildHookEntry uses Claude-shaped {type,command,timeout,marker} with --cli gemini", () => {
+    const entry = gemini.buildHookEntry("/usr/bin/failproofai", "BeforeTool", "user") as Record<string, unknown>;
+    expect(entry.type).toBe("command");
+    expect(entry.command).toBe('"/usr/bin/failproofai" --hook BeforeTool --cli gemini');
+    expect(entry.timeout).toBe(60_000);
+    expect(entry[FAILPROOFAI_HOOK_MARKER]).toBe(true);
+    // Gemini entries use Claude's `command` field, not Copilot's bash/powershell split.
+    expect(entry.bash).toBeUndefined();
+    expect(entry.powershell).toBeUndefined();
+  });
+
+  it("project scope uses npx -y failproofai (portable across machines)", () => {
+    const entry = gemini.buildHookEntry("/usr/bin/failproofai", "BeforeTool", "project") as Record<string, unknown>;
+    expect(entry.command).toBe("npx -y failproofai --hook BeforeTool --cli gemini");
+  });
+
+  it("writeHookEntries writes the matcher-wrapper schema for all 11 events with matcher='*'", () => {
+    const settings: Record<string, unknown> = {};
+    gemini.writeHookEntries(settings, "/usr/bin/failproofai", "user");
+    const hooks = settings.hooks as Record<string, Array<Record<string, unknown>>>;
+    for (const eventType of GEMINI_HOOK_EVENT_TYPES) {
+      expect(hooks[eventType]).toBeDefined();
+      const matchers = hooks[eventType];
+      expect(matchers.length).toBeGreaterThanOrEqual(1);
+      // Matcher-wrapper: each element is {matcher, hooks: [{type, command, ...}]}
+      expect(matchers[0].matcher).toBe("*");
+      const inner = matchers[0].hooks as Array<Record<string, unknown>>;
+      expect(inner).toHaveLength(1);
+      expect(inner[0].type).toBe("command");
+      expect(typeof inner[0].command).toBe("string");
+      expect(inner[0][FAILPROOFAI_HOOK_MARKER]).toBe(true);
+    }
+  });
+
+  it("re-running writeHookEntries is idempotent (replaces, doesn't duplicate)", () => {
+    const settings: Record<string, unknown> = {};
+    gemini.writeHookEntries(settings, "/usr/bin/failproofai", "user");
+    gemini.writeHookEntries(settings, "/different/path/failproofai", "user");
+    const hooks = settings.hooks as Record<string, Array<Record<string, unknown>>>;
+    // Each event has exactly one matcher; the inner hook is the most recent.
+    expect(hooks.BeforeTool).toHaveLength(1);
+    const inner = (hooks.BeforeTool[0].hooks as Array<Record<string, unknown>>)[0];
+    expect(inner.command).toBe('"/different/path/failproofai" --hook BeforeTool --cli gemini');
+  });
+
+  it("writeHookEntries preserves a hand-written user hook with the same event key", () => {
+    const userHook = { type: "command", command: "/my/script.sh", timeout: 5000 };
+    const settings: Record<string, unknown> = {
+      hooks: { BeforeTool: [{ matcher: "write_file", hooks: [userHook] }] },
+    };
+    gemini.writeHookEntries(settings, "/usr/bin/failproofai", "user");
+    const hooks = settings.hooks as Record<string, Array<Record<string, unknown>>>;
+    // User's hook is preserved at index 0, ours appended at index 1
+    expect(hooks.BeforeTool).toHaveLength(2);
+    const userMatcher = hooks.BeforeTool[0];
+    expect(userMatcher.matcher).toBe("write_file");
+    expect((userMatcher.hooks as Array<Record<string, unknown>>)[0].command).toBe("/my/script.sh");
+    const ourMatcher = hooks.BeforeTool[1];
+    expect(ourMatcher.matcher).toBe("*");
+    expect((ourMatcher.hooks as Array<Record<string, unknown>>)[0][FAILPROOFAI_HOOK_MARKER]).toBe(true);
+  });
+
+  it("removeHooksFromFile removes only failproofai-marked entries (preserves user hooks)", () => {
+    const userHook = { type: "command", command: "/my/script.sh", timeout: 5000 };
+    const settingsPath = gemini.getSettingsPath("project", tempDir);
+    mkdirSync(resolve(tempDir, ".gemini"), { recursive: true });
+    const settings: Record<string, unknown> = {
+      hooks: { BeforeTool: [{ matcher: "write_file", hooks: [userHook] }] },
+    };
+    gemini.writeHookEntries(settings, "/usr/bin/failproofai", "project");
+    gemini.writeSettings(settingsPath, settings);
+
+    const removed = gemini.removeHooksFromFile(settingsPath);
+    // 11 events × 1 marked entry each = 11 removed
+    expect(removed).toBe(GEMINI_HOOK_EVENT_TYPES.length);
+
+    const after = JSON.parse(readFileSync(settingsPath, "utf-8")) as Record<string, unknown>;
+    const afterHooks = after.hooks as Record<string, unknown[]>;
+    // User's BeforeTool hook still there
+    expect(afterHooks.BeforeTool).toHaveLength(1);
+    expect((afterHooks.BeforeTool[0] as Record<string, unknown>).matcher).toBe("write_file");
+    // Other event keys (which only had failproofai entries) are deleted
+    expect(afterHooks.SessionStart).toBeUndefined();
+  });
+
+  it("removeHooksFromFile clears all and removes the top-level hooks key when nothing remains", () => {
+    const settingsPath = gemini.getSettingsPath("project", tempDir);
+    mkdirSync(resolve(tempDir, ".gemini"), { recursive: true });
+    const settings: Record<string, unknown> = {};
+    gemini.writeHookEntries(settings, "/usr/bin/failproofai", "project");
+    gemini.writeSettings(settingsPath, settings);
+
+    const removed = gemini.removeHooksFromFile(settingsPath);
+    expect(removed).toBe(GEMINI_HOOK_EVENT_TYPES.length);
+
+    const after = JSON.parse(readFileSync(settingsPath, "utf-8")) as Record<string, unknown>;
+    expect(after.hooks).toBeUndefined();
+  });
+
+  it("hooksInstalledInSettings detects installed hooks", () => {
+    const settingsPath = gemini.getSettingsPath("project", tempDir);
+    mkdirSync(resolve(tempDir, ".gemini"), { recursive: true });
+    const settings: Record<string, unknown> = {};
+    gemini.writeHookEntries(settings, "/usr/bin/failproofai", "project");
+    gemini.writeSettings(settingsPath, settings);
+
+    expect(gemini.hooksInstalledInSettings("project", tempDir)).toBe(true);
+  });
+
+  it("hooksInstalledInSettings returns false when file is missing", () => {
+    expect(gemini.hooksInstalledInSettings("project", tempDir)).toBe(false);
+  });
+
+  it("hooksInstalledInSettings returns false on corrupt JSON (fail-open)", () => {
+    const settingsPath = gemini.getSettingsPath("project", tempDir);
+    mkdirSync(resolve(tempDir, ".gemini"), { recursive: true });
+    writeFileSync(settingsPath, "{not json");
+    expect(gemini.hooksInstalledInSettings("project", tempDir)).toBe(false);
+  });
+});
+
+describe("GEMINI_EVENT_MAP", () => {
+  it("maps every Gemini event to a canonical HookEventType (or passthrough)", () => {
+    expect(GEMINI_EVENT_MAP.SessionStart).toBe("SessionStart");
+    expect(GEMINI_EVENT_MAP.SessionEnd).toBe("SessionEnd");
+    expect(GEMINI_EVENT_MAP.BeforeAgent).toBe("UserPromptSubmit");
+    expect(GEMINI_EVENT_MAP.AfterAgent).toBe("Stop");
+    expect(GEMINI_EVENT_MAP.BeforeTool).toBe("PreToolUse");
+    expect(GEMINI_EVENT_MAP.AfterTool).toBe("PostToolUse");
+    expect(GEMINI_EVENT_MAP.PreCompress).toBe("PreCompact");
+    expect(GEMINI_EVENT_MAP.Notification).toBe("Notification");
+    // Three Gemini-only events have no canonical Claude equivalent — passthrough.
+    expect(GEMINI_EVENT_MAP.BeforeModel).toBe("BeforeModel");
+    expect(GEMINI_EVENT_MAP.AfterModel).toBe("AfterModel");
+    expect(GEMINI_EVENT_MAP.BeforeToolSelection).toBe("BeforeToolSelection");
+  });
+
+  it("GEMINI_EVENT_MAP keys exactly match GEMINI_HOOK_EVENT_TYPES", () => {
+    const mapKeys = Object.keys(GEMINI_EVENT_MAP).sort();
+    const eventTypes = [...GEMINI_HOOK_EVENT_TYPES].sort();
+    expect(mapKeys).toEqual(eventTypes);
+  });
+
+  it("GeminiHookEventType is exhaustive", () => {
+    const sample: GeminiHookEventType = "BeforeTool";
+    expect(GEMINI_EVENT_MAP[sample]).toBe("PreToolUse");
+  });
+});
+
+describe("GEMINI_TOOL_MAP", () => {
+  it("maps every documented Gemini snake_case tool name to a Claude PascalCase canonical name", () => {
+    expect(GEMINI_TOOL_MAP.run_shell_command).toBe("Bash");
+    expect(GEMINI_TOOL_MAP.read_file).toBe("Read");
+    expect(GEMINI_TOOL_MAP.read_many_files).toBe("Read");
+    expect(GEMINI_TOOL_MAP.write_file).toBe("Write");
+    expect(GEMINI_TOOL_MAP.replace).toBe("Edit");
+    expect(GEMINI_TOOL_MAP.glob).toBe("Glob");
+    expect(GEMINI_TOOL_MAP.grep_search).toBe("Grep");
+    expect(GEMINI_TOOL_MAP.list_directory).toBe("LS");
+    expect(GEMINI_TOOL_MAP.web_fetch).toBe("WebFetch");
+    expect(GEMINI_TOOL_MAP.google_web_search).toBe("WebSearch");
+    expect(GEMINI_TOOL_MAP.write_todos).toBe("TodoWrite");
+    expect(GEMINI_TOOL_MAP.save_memory).toBe("Memory");
+    expect(GEMINI_TOOL_MAP.ask_user).toBe("AskUser");
+  });
+});
diff --git a/__tests__/hooks/policy-evaluator.test.ts b/__tests__/hooks/policy-evaluator.test.ts
index 1992e628..ea10bf6b 100644
--- a/__tests__/hooks/policy-evaluator.test.ts
+++ b/__tests__/hooks/policy-evaluator.test.ts
@@ -703,4 +703,193 @@ describe("hooks/policy-evaluator", () => {
       expect(result.reason).toBe("hard block. deny hint");
     });
   });
+
+  describe("Gemini CLI response shape", () => {
+    const geminiSession = (hookEventName: string) => ({
+      sessionId: "g-1", cwd: "/tmp", cli: "gemini" as const, hookEventName,
+    });
+
+    it("PreToolUse deny → flat {decision:'deny', reason} (NOT Claude's hookSpecificOutput shape)", async () => {
+      registerPolicy("blocker", "desc", () => ({ decision: "deny", reason: "sudo blocked" }), {
+        events: ["PreToolUse"],
+      });
+      const result = await evaluatePolicies(
+        "PreToolUse",
+        { tool_name: "Bash", tool_input: { command: "sudo ls" } },
+        geminiSession("BeforeTool"),
+      );
+      expect(result.exitCode).toBe(0);
+      expect(result.stderr).toBe("");
+      const parsed = JSON.parse(result.stdout);
+      expect(parsed.decision).toBe("deny");
+      expect(parsed.reason).toContain("sudo blocked");
+      expect(parsed.reason).toContain("Blocked Bash by failproofai");
+      // Crucial: NOT Claude's nested shape
+      expect(parsed.hookSpecificOutput).toBeUndefined();
+    });
+
+    it("BeforeAgent deny (UserPromptSubmit) → flat {decision:'deny', reason}", async () => {
+      registerPolicy("prompt-block", "desc", () => ({ decision: "deny", reason: "bad prompt" }), {
+        events: ["UserPromptSubmit"],
+      });
+      const result = await evaluatePolicies(
+        "UserPromptSubmit",
+        { prompt: "<bad>" },
+        geminiSession("BeforeAgent"),
+      );
+      expect(result.exitCode).toBe(0);
+      const parsed = JSON.parse(result.stdout);
+      expect(parsed.decision).toBe("deny");
+      expect(parsed.reason).toContain("bad prompt");
+      expect(parsed.hookSpecificOutput).toBeUndefined();
+    });
+
+    it("AfterAgent deny (Stop) → {decision:'block', reason} with MANDATORY ACTION REQUIRED prefix", async () => {
+      registerPolicy("must-do", "desc", () => ({ decision: "deny", reason: "missing CHANGELOG" }), {
+        events: ["Stop"],
+      });
+      const result = await evaluatePolicies(
+        "Stop",
+        {},
+        geminiSession("AfterAgent"),
+      );
+      expect(result.exitCode).toBe(0);
+      const parsed = JSON.parse(result.stdout);
+      // Gemini's AfterAgent supports "Retry / Halt" via decision: "block"
+      expect(parsed.decision).toBe("block");
+      expect(parsed.reason).toContain("MANDATORY ACTION REQUIRED");
+      expect(parsed.reason).toContain("missing CHANGELOG");
+    });
+
+    it("instruct on PreToolUse → {hookSpecificOutput:{hookEventName:'BeforeTool', additionalContext}}", async () => {
+      registerPolicy("advisor", "desc", () => ({ decision: "instruct", reason: "consider X" }), {
+        events: ["PreToolUse"],
+      });
+      const result = await evaluatePolicies(
+        "PreToolUse",
+        { tool_name: "Bash" },
+        geminiSession("BeforeTool"),
+      );
+      expect(result.exitCode).toBe(0);
+      const parsed = JSON.parse(result.stdout);
+      // hookEventName must be the Gemini event name (not the canonical PreToolUse)
+      expect(parsed.hookSpecificOutput.hookEventName).toBe("BeforeTool");
+      expect(parsed.hookSpecificOutput.additionalContext).toContain("Instruction from failproofai");
+      expect(parsed.hookSpecificOutput.additionalContext).toContain("consider X");
+      // Must NOT use Gemini's flat block shape — that's reserved for deny
+      expect(parsed.decision).toBeUndefined();
+    });
+
+    it("instruct on AfterTool → {hookSpecificOutput:{hookEventName:'AfterTool', additionalContext}}", async () => {
+      registerPolicy("after", "desc", () => ({ decision: "instruct", reason: "post note" }), {
+        events: ["PostToolUse"],
+      });
+      const result = await evaluatePolicies(
+        "PostToolUse",
+        { tool_name: "Read" },
+        geminiSession("AfterTool"),
+      );
+      const parsed = JSON.parse(result.stdout);
+      expect(parsed.hookSpecificOutput.hookEventName).toBe("AfterTool");
+      expect(parsed.hookSpecificOutput.additionalContext).toContain("post note");
+    });
+
+    it("instruct on SessionStart → {hookSpecificOutput:{hookEventName:'SessionStart', additionalContext}}", async () => {
+      registerPolicy("greet", "desc", () => ({ decision: "instruct", reason: "warm context" }), {
+        events: ["SessionStart"],
+      });
+      const result = await evaluatePolicies(
+        "SessionStart",
+        {},
+        geminiSession("SessionStart"),
+      );
+      const parsed = JSON.parse(result.stdout);
+      expect(parsed.hookSpecificOutput.hookEventName).toBe("SessionStart");
+      expect(parsed.hookSpecificOutput.additionalContext).toContain("warm context");
+    });
+
+    it("instruct on AfterAgent (Stop) → {decision:'block', reason} with MANDATORY ACTION", async () => {
+      registerPolicy("must-do", "desc", () => ({ decision: "instruct", reason: "open the PR" }), {
+        events: ["Stop"],
+      });
+      const result = await evaluatePolicies(
+        "Stop",
+        {},
+        geminiSession("AfterAgent"),
+      );
+      const parsed = JSON.parse(result.stdout);
+      // For Gemini AfterAgent, both deny and instruct map to {decision: "block"} which forces a retry.
+      expect(parsed.decision).toBe("block");
+      expect(parsed.reason).toContain("MANDATORY ACTION REQUIRED");
+      expect(parsed.reason).toContain("open the PR");
+    });
+
+    it("multiple instruct on AfterAgent → reasons concatenated, single {decision:'block'} response", async () => {
+      registerPolicy("a", "desc", () => ({ decision: "instruct", reason: "first" }), { events: ["Stop"] });
+      registerPolicy("b", "desc", () => ({ decision: "instruct", reason: "second" }), { events: ["Stop"] });
+      const result = await evaluatePolicies(
+        "Stop",
+        {},
+        geminiSession("AfterAgent"),
+      );
+      const parsed = JSON.parse(result.stdout);
+      expect(parsed.decision).toBe("block");
+      expect(parsed.reason).toContain("first");
+      expect(parsed.reason).toContain("second");
+    });
+
+    it("instruct on a non-context-injection event (e.g. SessionEnd) → stderr only, no stdout JSON", async () => {
+      registerPolicy("byebye", "desc", () => ({ decision: "instruct", reason: "after-note" }), {
+        events: ["SessionEnd"],
+      });
+      const result = await evaluatePolicies(
+        "SessionEnd",
+        {},
+        geminiSession("SessionEnd"),
+      );
+      // SessionEnd is observation-only on Gemini; we don't emit a stdout JSON shape
+      expect(result.stdout).toBe("");
+      // Reason still surfaces via stderr for visibility
+      expect(result.stderr).toContain("after-note");
+    });
+
+    it("allow with informational reason on BeforeAgent → context-injection shape", async () => {
+      registerPolicy("info", "desc", () => ({ decision: "allow", reason: "fyi" }), {
+        events: ["UserPromptSubmit"],
+      });
+      const result = await evaluatePolicies(
+        "UserPromptSubmit",
+        { prompt: "x" },
+        geminiSession("BeforeAgent"),
+      );
+      const parsed = JSON.parse(result.stdout);
+      expect(parsed.hookSpecificOutput.hookEventName).toBe("BeforeAgent");
+      expect(parsed.hookSpecificOutput.additionalContext).toContain("Note from failproofai");
+      expect(parsed.hookSpecificOutput.additionalContext).toContain("fyi");
+    });
+
+    it("allow with informational reason on SessionEnd → stderr only", async () => {
+      registerPolicy("info", "desc", () => ({ decision: "allow", reason: "fyi" }), {
+        events: ["SessionEnd"],
+      });
+      const result = await evaluatePolicies(
+        "SessionEnd",
+        {},
+        geminiSession("SessionEnd"),
+      );
+      expect(result.stdout).toBe("");
+      expect(result.stderr).toContain("fyi");
+    });
+
+    it("allow without reason → empty stdout, exit 0 (no extra noise)", async () => {
+      registerPolicy("ok", "desc", () => ({ decision: "allow" }), { events: ["PreToolUse"] });
+      const result = await evaluatePolicies(
+        "PreToolUse",
+        { tool_name: "Bash" },
+        geminiSession("BeforeTool"),
+      );
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toBe("");
+    });
+  });
 });
diff --git a/bin/failproofai.mjs b/bin/failproofai.mjs
index 9771d5b4..c4084207 100755
--- a/bin/failproofai.mjs
+++ b/bin/failproofai.mjs
@@ -43,7 +43,7 @@ const hookIdx = args.indexOf("--hook");
 if (hookIdx >= 0) {
   if (!args[hookIdx + 1]) {
     console.error("Error: Missing event type after --hook");
-    console.error("Usage: failproofai --hook <event> [--cli <claude|codex|copilot|cursor|opencode|pi>]");
+    console.error("Usage: failproofai --hook <event> [--cli <claude|codex|copilot|cursor|opencode|pi|gemini>]");
     process.exit(1);
   }
   const eventType = args[hookIdx + 1];
@@ -59,6 +59,7 @@ if (hookIdx >= 0) {
       || cliArg === "cursor"
       || cliArg === "opencode"
       || cliArg === "pi"
+      || cliArg === "gemini"
     )
       ? cliArg
       : "claude";
@@ -112,18 +113,18 @@ COMMANDS
   policies, p                    List all available policies and their status
   policies --install, -i         Enable policies in agent CLI settings
     [names...]                     Specific policy names to enable
-    --cli claude|codex|copilot|cursor|opencode|pi
+    --cli claude|codex|copilot|cursor|opencode|pi|gemini
                                    Agent CLI(s) to install for; space-separated
-                                   (e.g. --cli claude codex copilot cursor opencode pi) or repeated.
+                                   (e.g. --cli claude codex copilot cursor opencode pi gemini) or repeated.
                                    Default: detect installed CLIs and prompt.
     --scope user|project|local     Config scope to write to (default: user)
-                                   (Codex / Copilot / Cursor / OpenCode / Pi support user|project only)
+                                   (Codex / Copilot / Cursor / OpenCode / Pi / Gemini support user|project only)
     --beta                         Include beta policies
     --custom, -c <path>            Path to a JS file of custom policies
 
   policies --uninstall, -u       Disable policies or remove hooks
     [names...]                     Specific policy names to disable
-    --cli claude|codex|copilot|cursor|opencode|pi
+    --cli claude|codex|copilot|cursor|opencode|pi|gemini
                                    Agent CLI(s) to uninstall from
     --scope user|project|local|all Config scope to remove from (default: user)
     --beta                         Remove only beta policies
@@ -154,7 +155,8 @@ EXAMPLES
   failproofai policies --install --cli cursor --scope project
   failproofai policies --install --cli opencode --scope project
   failproofai policies --install --cli pi --scope project
-  failproofai policies --install --cli claude codex copilot cursor opencode pi
+  failproofai policies --install --cli gemini --scope project
+  failproofai policies --install --cli claude codex copilot cursor opencode pi gemini
   failproofai policies --install --custom ./my-policies.js
   failproofai policies -i -c ./my-policies.js
   failproofai policies --uninstall block-sudo
@@ -163,6 +165,7 @@ EXAMPLES
   failproofai policies --uninstall --cli cursor
   failproofai policies --uninstall --cli opencode
   failproofai policies --uninstall --cli pi
+  failproofai policies --uninstall --cli gemini
   failproofai policies --uninstall --custom
 
 LINKS
@@ -202,20 +205,20 @@ USAGE
 
 OPTIONS (install)
   [names...]                     Specific policy names to enable (omit for interactive)
-  --cli claude|codex|copilot|cursor|opencode|pi
+  --cli claude|codex|copilot|cursor|opencode|pi|gemini
                                  Agent CLI(s) to install for; space-separated
-                                 (e.g. --cli claude codex copilot cursor opencode pi) or repeated.
+                                 (e.g. --cli claude codex copilot cursor opencode pi gemini) or repeated.
                                  Omit to detect installed CLIs and prompt (or
                                  auto-pick if only one is found).
   --scope user|project|local     Config scope to write to (default: user)
-                                 (Codex / Copilot / Cursor / OpenCode / Pi support user|project only)
+                                 (Codex / Copilot / Cursor / OpenCode / Pi / Gemini support user|project only)
   --beta                         Include beta policies
   --custom, -c <path>            Path to a JS file of custom policies
                                  (skips interactive prompt; validates file first)
 
 OPTIONS (uninstall)
   [names...]                     Specific policy names to disable (omit to remove hooks)
-  --cli claude|codex|copilot|cursor|opencode|pi
+  --cli claude|codex|copilot|cursor|opencode|pi|gemini
                                  Agent CLI(s) to uninstall from
   --scope user|project|local|all Config scope to remove from (default: user)
   --beta                         Remove only beta policies
@@ -230,7 +233,8 @@ EXAMPLES
   failproofai policies --install --cli cursor --scope project
   failproofai policies --install --cli opencode --scope project
   failproofai policies --install --cli pi --scope project
-  failproofai policies --install --cli claude codex copilot cursor opencode pi
+  failproofai policies --install --cli gemini --scope project
+  failproofai policies --install --cli claude codex copilot cursor opencode pi gemini
   failproofai policies --install --custom ./my-policies.js
   failproofai policies -i -c ./my-policies.js
   failproofai policies --uninstall block-sudo
@@ -270,7 +274,7 @@ EXAMPLES
       //   --cli claude codex copilot
       //   --cli claude --cli codex
       // Values are consumed greedily until the next flag or end of argv.
-      const VALID_CLIS = new Set(["claude", "codex", "copilot", "cursor", "opencode", "pi"]);
+      const VALID_CLIS = new Set(["claude", "codex", "copilot", "cursor", "opencode", "pi", "gemini"]);
       const cliFlagValues = [];
       const cliConsumedIdxs = new Set();
       const cliFlagIdxs = subArgs.map((a, i) => (a === "--cli" ? i : -1)).filter((i) => i >= 0);
@@ -287,7 +291,7 @@ EXAMPLES
           consumed++;
         }
         if (consumed === 0) {
-          throw new CliError("Missing value(s) for --cli. Usage: --cli claude codex copilot cursor opencode pi (or any subset)");
+          throw new CliError("Missing value(s) for --cli. Usage: --cli claude codex copilot cursor opencode pi gemini (or any subset)");
         }
       }
 
@@ -350,7 +354,7 @@ EXAMPLES
       }
 
       // --cli accepts one or more space-separated values; same parser as install.
-      const VALID_CLIS = new Set(["claude", "codex", "copilot", "cursor", "opencode", "pi"]);
+      const VALID_CLIS = new Set(["claude", "codex", "copilot", "cursor", "opencode", "pi", "gemini"]);
       const cliFlagValues = [];
       const cliConsumedIdxs = new Set();
       const cliFlagIdxs = subArgs.map((a, i) => (a === "--cli" ? i : -1)).filter((i) => i >= 0);
@@ -367,7 +371,7 @@ EXAMPLES
           consumed++;
         }
         if (consumed === 0) {
-          throw new CliError("Missing value(s) for --cli. Usage: --cli claude codex copilot cursor opencode pi (or any subset)");
+          throw new CliError("Missing value(s) for --cli. Usage: --cli claude codex copilot cursor opencode pi gemini (or any subset)");
         }
       }
 
diff --git a/src/hooks/builtin-policies.ts b/src/hooks/builtin-policies.ts
index 4c82c6c1..039f4ede 100644
--- a/src/hooks/builtin-policies.ts
+++ b/src/hooks/builtin-policies.ts
@@ -12,8 +12,8 @@ import { hookLogWarn } from "./hook-logger";
 
 /**
  * Whether `resolved` lives under an agent CLI's home directory
- * (~/.claude/, ~/.codex/, ~/.copilot/, ~/.cursor/, ~/.pi/, or any of
- * OpenCode's three home-side dirs). Used to whitelist agent self-reads of
+ * (~/.claude/, ~/.codex/, ~/.copilot/, ~/.cursor/, ~/.pi/, ~/.gemini/, or any
+ * of OpenCode's three home-side dirs). Used to whitelist agent self-reads of
  * their own config and transcripts.
  *
  * OpenCode splits its data across three locations (verified live on
@@ -29,7 +29,7 @@ function isAgentInternalPath(resolved: string): boolean {
   // convention. Comparing both sides under a single forward-slash form
   // avoids per-OS branching.
   const normResolved = resolved.replaceAll("\\", "/");
-  for (const dir of [".claude", ".codex", ".copilot", ".cursor", ".opencode", ".pi"]) {
+  for (const dir of [".claude", ".codex", ".copilot", ".cursor", ".opencode", ".pi", ".gemini"]) {
     const root = join(homedir(), dir).replaceAll("\\", "/");
     if (normResolved === root || normResolved.startsWith(root + "/")) return true;
   }
@@ -53,6 +53,9 @@ function isAgentInternalPath(resolved: string): boolean {
  *   • Pi:           `.pi/settings.json` (project) and `.pi/agent/settings.json`
  *                   (user); also the Pi-managed extension dir
  *                   `.pi/extensions/` / `.pi/agent/extensions/`.
+ *   • Gemini CLI:   `.gemini/settings.json` (both project and user scope —
+ *                   user is `~/.gemini/settings.json`); also the Gemini-managed
+ *                   hooks scripts dir `.gemini/hooks/`.
  * These must NEVER be edited by the agent itself — that would let it disable
  * its own protections.
  */
@@ -71,6 +74,9 @@ function isAgentSettingsFile(resolved: string): boolean {
   // Pi: settings + extensions dirs (project and user-scope variants).
   if (/[\\/]\.pi[\\/](?:agent[\\/])?settings\.json$/.test(resolved)) return true;
   if (/[\\/]\.pi[\\/](?:agent[\\/])?extensions[\\/]/.test(resolved)) return true;
+  // Gemini: settings.json + hooks dir referenced by `command: $GEMINI_PROJECT_DIR/.gemini/hooks/...`.
+  if (/[\\/]\.gemini[\\/]settings\.json$/.test(resolved)) return true;
+  if (/[\\/]\.gemini[\\/]hooks[\\/]/.test(resolved)) return true;
   return false;
 }
 
diff --git a/src/hooks/handler.ts b/src/hooks/handler.ts
index bf873996..f7c27aed 100644
--- a/src/hooks/handler.ts
+++ b/src/hooks/handler.ts
@@ -12,8 +12,9 @@ import type {
   CodexHookEventType,
   CursorHookEventType,
   PiHookEventType,
+  GeminiHookEventType,
 } from "./types";
-import { CODEX_EVENT_MAP, CURSOR_EVENT_MAP, PI_EVENT_MAP } from "./types";
+import { CODEX_EVENT_MAP, CURSOR_EVENT_MAP, PI_EVENT_MAP, GEMINI_EVENT_MAP, GEMINI_TOOL_MAP } from "./types";
 import type { PolicyFunction, PolicyResult } from "./policy-types";
 import { readMergedHooksConfig } from "./hooks-config";
 import { registerBuiltinPolicies } from "./builtin-policies";
@@ -33,8 +34,10 @@ import { hookLogInfo, hookLogWarn } from "./hook-logger";
  * `beforeSubmitPrompt`); Pi sends underscore_lower_snake_case (`tool_call`,
  * `session_start`); Claude Code sends PascalCase. Copilot CLI is installed
  * in "VS Code compatible" PascalCase mode (see integrations.ts), so its events
- * arrive PascalCase already. The internal registry, builtin policies, and
- * policy.match.events all key on PascalCase.
+ * arrive PascalCase already. Gemini also sends PascalCase but with different
+ * names (`BeforeTool`, `BeforeAgent`, `AfterAgent`); we map via GEMINI_EVENT_MAP.
+ * The internal registry, builtin policies, and policy.match.events all key on
+ * PascalCase.
  */
 function canonicalizeEventType(raw: string, cli: IntegrationType): HookEventType {
   if (cli === "codex") {
@@ -49,11 +52,34 @@ function canonicalizeEventType(raw: string, cli: IntegrationType): HookEventType
     const mapped = PI_EVENT_MAP[raw as PiHookEventType];
     if (mapped) return mapped;
   }
+  if (cli === "gemini") {
+    const mapped = GEMINI_EVENT_MAP[raw as GeminiHookEventType];
+    if (mapped) return mapped;
+  }
   // claude / copilot / unknown — already PascalCase, pass through.
   // HOOK_EVENT_TYPES type-checks downstream.
   return raw as HookEventType;
 }
 
+/**
+ * Canonicalize a per-CLI tool name to the Claude PascalCase form that builtin
+ * policies match on (e.g. `Bash`, `Read`, `Write`, `Edit`). Today only Gemini
+ * needs this — its tools are snake_case (`run_shell_command`, `read_file`,
+ * `write_file`, `replace`, …). Other CLIs pass through unchanged: Claude /
+ * Codex / Copilot already use PascalCase, and Cursor / Pi pre-canonicalize
+ * inside their own plugin shims before the payload reaches this binary.
+ *
+ * Unknown tool names (MCP `mcp_*`, third-party extensions, Skills) pass
+ * through unchanged so non-builtin tooling isn't lost.
+ */
+function canonicalizeToolName(raw: string | undefined, cli: IntegrationType): string | undefined {
+  if (!raw) return raw;
+  if (cli === "gemini") {
+    return GEMINI_TOOL_MAP[raw] ?? raw;
+  }
+  return raw;
+}
+
 export async function handleHookEvent(
   eventType: string,
   cli: IntegrationType = "claude",
@@ -99,6 +125,17 @@ export async function handleHookEvent(
   // Canonicalize event name (Codex sends snake_case; internals expect PascalCase)
   const canonicalEventType = canonicalizeEventType(eventType, cli);
 
+  // Canonicalize tool name in place so both the policy-registry tool-name
+  // filter and policy bodies (`ctx.toolName === "Bash"`) see the canonical
+  // form. Today only Gemini's snake_case names need translation; other CLIs
+  // are no-ops here. Mutating `parsed.tool_name` keeps the activity store +
+  // telemetry tagging consistent (they read from `parsed.tool_name`).
+  const rawToolName = parsed.tool_name as string | undefined;
+  const canonicalToolName = canonicalizeToolName(rawToolName, cli);
+  if (canonicalToolName !== rawToolName) {
+    parsed.tool_name = canonicalToolName;
+  }
+
   // Extract session metadata from payload
   const sessionId = parsed.session_id as string | undefined;
   const session: SessionMetadata = {
diff --git a/src/hooks/install-prompt.ts b/src/hooks/install-prompt.ts
index 99e83113..356b482f 100644
--- a/src/hooks/install-prompt.ts
+++ b/src/hooks/install-prompt.ts
@@ -60,13 +60,13 @@ export async function resolveTargetClis(
       // Uninstall flow: no agent CLIs detected — nothing to remove from. Default to
       // claude so removeHooks operates over Claude's scopes (no-op if no settings file).
       console.log(
-        "\x1B[33mWarning: no agent CLI binary found in PATH (claude, codex, copilot, cursor-agent, opencode, pi). " +
+        "\x1B[33mWarning: no agent CLI binary found in PATH (claude, codex, copilot, cursor-agent, opencode, pi, gemini). " +
           "Defaulting to Claude Code; nothing will be removed if no settings file exists.\x1B[0m",
       );
       return ["claude"];
     }
     console.log(
-      "\x1B[33mWarning: no agent CLI binary found in PATH (claude, codex, copilot, cursor-agent, opencode, pi). " +
+      "\x1B[33mWarning: no agent CLI binary found in PATH (claude, codex, copilot, cursor-agent, opencode, pi, gemini). " +
         "Defaulting to Claude Code; hooks will activate when an agent is installed.\x1B[0m",
     );
     return ["claude"];
diff --git a/src/hooks/integrations.ts b/src/hooks/integrations.ts
index 1cc0b957..ba0a9ad3 100644
--- a/src/hooks/integrations.ts
+++ b/src/hooks/integrations.ts
@@ -25,6 +25,8 @@ import {
   OPENCODE_HOOK_SCOPES,
   PI_HOOK_EVENT_TYPES,
   PI_HOOK_SCOPES,
+  GEMINI_HOOK_EVENT_TYPES,
+  GEMINI_HOOK_SCOPES,
   FAILPROOFAI_HOOK_MARKER,
   INTEGRATION_TYPES,
   type IntegrationType,
@@ -1185,6 +1187,163 @@ function makePiProjectRelativeEntry(extPath: string): string {
   // works for the local user.
   return extResolved;
 }
+// ── Gemini CLI integration ──────────────────────────────────────────────────
+//
+// Gemini's hook contract is the closest thing to a Claude Code clone we've
+// shipped: same `{matcher, hooks: [{type, command, timeout}]}` settings shape,
+// PascalCase event names, snake_case stdin payload field names (session_id,
+// tool_name, tool_input, hook_event_name, cwd, transcript_path), subprocess
+// execution model, and `$CLAUDE_PROJECT_DIR` env-var alias on top of its own
+// `$GEMINI_PROJECT_DIR`. The integration is structurally identical to
+// claudeCode below, with three deltas:
+//
+//   • Settings paths: ~/.gemini/settings.json (user) / <cwd>/.gemini/settings.json (project).
+//     System scope (/etc/gemini-cli/settings.json) is documented but not exposed.
+//
+//   • Matcher field: each Gemini matcher entry carries an explicit `matcher`
+//     regex (e.g. `"write_file|replace"`). We default to `"*"` so policies fire
+//     on every tool call, mirroring the failproofai default of "every event,
+//     every tool". Users can hand-edit settings.json to scope tighter; we
+//     preserve their `matcher` field across re-installs by NOT replacing
+//     entries that aren't failproofai-marked.
+//
+//   • Tool name canonicalization happens in handler.ts (snake_case →
+//     PascalCase via GEMINI_TOOL_MAP) so policies match unchanged; not the
+//     install layer's concern.
+//
+// Detected via the `gemini` binary on PATH.
+//
+// Ref: https://geminicli.com/docs/hooks/
+
+interface GeminiHookMatcher {
+  matcher?: string;
+  hooks?: Array<ClaudeHookEntry | Record<string, unknown>>;
+}
+
+interface GeminiSettingsFile {
+  hooks?: Record<string, GeminiHookMatcher[]>;
+  [key: string]: unknown;
+}
+
+export const gemini: Integration = {
+  id: "gemini",
+  displayName: "Gemini CLI",
+  scopes: GEMINI_HOOK_SCOPES,
+  eventTypes: GEMINI_HOOK_EVENT_TYPES,
+
+  getSettingsPath(scope, cwd) {
+    const base = cwd ? resolve(cwd) : process.cwd();
+    switch (scope) {
+      case "user":
+        return resolve(homedir(), ".gemini", "settings.json");
+      case "project":
+        return resolve(base, ".gemini", "settings.json");
+      case "local":
+        // Gemini has no "local" scope; CLI rejects --cli gemini --scope local
+        // before reaching here, but fall back to project so callers don't crash.
+        return resolve(base, ".gemini", "settings.json");
+    }
+  },
+
+  readSettings(settingsPath) {
+    return readJsonFile(settingsPath);
+  },
+
+  writeSettings(settingsPath, settings) {
+    writeJsonFile(settingsPath, settings);
+  },
+
+  buildHookEntry(binaryPath, eventType, scope) {
+    const command =
+      scope === "project"
+        ? `npx -y failproofai --hook ${eventType} --cli gemini`
+        : `"${binaryPath}" --hook ${eventType} --cli gemini`;
+    return {
+      type: "command",
+      command,
+      timeout: 60_000,
+      [FAILPROOFAI_HOOK_MARKER]: true,
+    };
+  },
+
+  isFailproofaiHook: isMarkedHook,
+
+  writeHookEntries(settings, binaryPath, scope) {
+    const s = settings as GeminiSettingsFile;
+    if (!s.hooks) s.hooks = {};
+
+    for (const eventType of GEMINI_HOOK_EVENT_TYPES) {
+      const hookEntry = this.buildHookEntry(binaryPath, eventType, scope) as unknown as ClaudeHookEntry;
+      if (!s.hooks[eventType]) s.hooks[eventType] = [];
+      const matchers: GeminiHookMatcher[] = s.hooks[eventType];
+
+      // Idempotent: replace an existing failproofai-marked entry inside our
+      // own matcher; otherwise append a new `{matcher: "*", hooks: [...]}`.
+      // Hand-written matchers (with their own `matcher` regex) are never
+      // touched — we identify our matcher by checking whether ANY of its
+      // inner hooks are failproofai-marked.
+      let found = false;
+      for (const matcher of matchers) {
+        if (!matcher.hooks) continue;
+        const idx = matcher.hooks.findIndex((h) => isMarkedHook(h as Record<string, unknown>));
+        if (idx >= 0) {
+          matcher.hooks[idx] = hookEntry;
+          found = true;
+          break;
+        }
+      }
+      if (!found) matchers.push({ matcher: "*", hooks: [hookEntry] });
+    }
+  },
+
+  removeHooksFromFile(settingsPath) {
+    const settings = this.readSettings(settingsPath) as GeminiSettingsFile;
+    if (!settings.hooks) return 0;
+
+    let removed = 0;
+    for (const eventType of Object.keys(settings.hooks)) {
+      const matchers = settings.hooks[eventType];
+      if (!Array.isArray(matchers)) continue;
+      for (let i = matchers.length - 1; i >= 0; i--) {
+        const matcher = matchers[i];
+        if (!matcher.hooks) continue;
+        const before = matcher.hooks.length;
+        matcher.hooks = matcher.hooks.filter((h) => !isMarkedHook(h as Record<string, unknown>));
+        removed += before - matcher.hooks.length;
+        if (matcher.hooks.length === 0) matchers.splice(i, 1);
+      }
+      if (matchers.length === 0) delete settings.hooks[eventType];
+    }
+    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+
+    this.writeSettings(settingsPath, settings as Record<string, unknown>);
+    return removed;
+  },
+
+  hooksInstalledInSettings(scope, cwd) {
+    const settingsPath = this.getSettingsPath(scope, cwd);
+    if (!existsSync(settingsPath)) return false;
+    try {
+      const settings = this.readSettings(settingsPath) as GeminiSettingsFile;
+      if (!settings.hooks) return false;
+      for (const matchers of Object.values(settings.hooks)) {
+        if (!Array.isArray(matchers)) continue;
+        for (const matcher of matchers) {
+          if (!matcher.hooks) continue;
+          if (matcher.hooks.some((h) => isMarkedHook(h as Record<string, unknown>))) return true;
+        }
+      }
+    } catch {
+      // Corrupt settings — treat as not installed
+    }
+    return false;
+  },
+
+  detectInstalled() {
+    return binaryExists("gemini");
+  },
+};
+
 // ── Registry ────────────────────────────────────────────────────────────────
 
 const INTEGRATIONS: Record<IntegrationType, Integration> = {
@@ -1194,6 +1353,7 @@ const INTEGRATIONS: Record<IntegrationType, Integration> = {
   cursor,
   opencode,
   pi,
+  gemini,
 };
 
 export function getIntegration(id: IntegrationType): Integration {
diff --git a/src/hooks/policy-evaluator.ts b/src/hooks/policy-evaluator.ts
index cae98c23..45434ceb 100644
--- a/src/hooks/policy-evaluator.ts
+++ b/src/hooks/policy-evaluator.ts
@@ -163,6 +163,33 @@ export async function evaluatePolicies(
         };
       }
 
+      // Gemini CLI: flat `{decision: "deny", reason}` for non-Stop events
+      // (preferred per Gemini's "Golden Rule" — exit 0 with structured JSON).
+      // For Stop (AfterAgent), use `{decision: "block", reason}` to force-retry,
+      // mirroring Claude's exit-2-from-Stop "do this before stopping" semantics.
+      // Ref: https://geminicli.com/docs/hooks/
+      if (session?.cli === "gemini") {
+        if (eventType === "Stop") {
+          const reasonText = `MANDATORY ACTION REQUIRED from failproofai (policy: ${policy.name}): ${reason}\n\nYou MUST complete the above action NOW. Do NOT ask the user for confirmation — execute the required action, then attempt to finish your task again.`;
+          return {
+            exitCode: 0,
+            stdout: JSON.stringify({ decision: "block", reason: reasonText }),
+            stderr: "",
+            policyName: policy.name,
+            reason,
+            decision: "deny",
+          };
+        }
+        return {
+          exitCode: 0,
+          stdout: JSON.stringify({ decision: "deny", reason: blockedMessage }),
+          stderr: "",
+          policyName: policy.name,
+          reason,
+          decision: "deny",
+        };
+      }
+
       if (eventType === "PreToolUse") {
         const response = {
           hookSpecificOutput: {
@@ -317,6 +344,72 @@ export async function evaluatePolicies(
       };
     }
 
+    // Gemini CLI:
+    //   • Stop (AfterAgent) → {decision: "block", reason: "MANDATORY ACTION..."}
+    //     mirrors Claude's exit-2-from-Stop "force retry" semantics.
+    //   • UserPromptSubmit/PostToolUse/SessionStart/PreToolUse → context
+    //     injection via {hookSpecificOutput: {hookEventName, additionalContext}}
+    //     where hookEventName is the GEMINI event name (BeforeAgent/AfterTool/
+    //     SessionStart/BeforeTool), not the canonical PascalCase form.
+    //   • Other events → stderr only (no stdout JSON shape supported).
+    if (session?.cli === "gemini") {
+      if (eventType === "Stop") {
+        const policyAttribution = policyNames.length === 1
+          ? `policy: ${policyNames[0]}`
+          : `policies: ${policyNames.join(", ")}`;
+        const reasonText = `MANDATORY ACTION REQUIRED from failproofai (${policyAttribution}): ${combined}\n\nYou MUST complete the above action(s) NOW. Do NOT ask the user for confirmation — execute the required action(s), then attempt to finish your task again.`;
+        return {
+          exitCode: 0,
+          stdout: JSON.stringify({ decision: "block", reason: reasonText }),
+          stderr: "",
+          policyName: policyNames[0],
+          policyNames,
+          reason: combined,
+          decision: "instruct",
+        };
+      }
+      // Map back from canonical → Gemini event name. Prefer the raw event name
+      // off the session (handler.ts populates it from parsed.hook_event_name)
+      // so we don't have to maintain a reverse lookup table.
+      const supportsContext =
+        eventType === "UserPromptSubmit" ||
+        eventType === "PreToolUse" ||
+        eventType === "PostToolUse" ||
+        eventType === "SessionStart";
+      if (supportsContext) {
+        const hookEventName = session?.hookEventName ?? eventType;
+        const response = {
+          hookSpecificOutput: {
+            hookEventName,
+            additionalContext: `Instruction from failproofai: ${combined}`,
+          },
+        };
+        return {
+          exitCode: 0,
+          stdout: JSON.stringify(response),
+          stderr: "",
+          policyName: policyNames[0],
+          policyNames,
+          reason: combined,
+          decision: "instruct",
+        };
+      }
+      // No context-injection channel for SessionEnd/PreCompress/Notification/
+      // BeforeModel/AfterModel/BeforeToolSelection — surface via stderr only.
+      const stderrMsg = instructEntries
+        .map((e) => `[failproofai] ${e.policyName}: ${e.reason}`)
+        .join("\n");
+      return {
+        exitCode: 0,
+        stdout: "",
+        stderr: stderrMsg + "\n",
+        policyName: policyNames[0],
+        policyNames,
+        reason: combined,
+        decision: "instruct",
+      };
+    }
+
     if (eventType === "Stop") {
       // Stop hook: exitCode 2 blocks Claude from stopping.
       // Reason goes to stderr so Claude Code receives it as context.
@@ -397,6 +490,46 @@ export async function evaluatePolicies(
       };
     }
 
+    // Gemini: mirror the instruct context-injection shape for events that
+    // support it; stderr-only for everything else.
+    if (session?.cli === "gemini") {
+      const supportsContext =
+        eventType === "UserPromptSubmit" ||
+        eventType === "PreToolUse" ||
+        eventType === "PostToolUse" ||
+        eventType === "SessionStart";
+      const stderrMsg = allowEntries
+        .map((e) => `[failproofai] ${e.policyName}: ${e.reason}`)
+        .join("\n");
+      if (supportsContext) {
+        const hookEventName = session?.hookEventName ?? eventType;
+        const response = {
+          hookSpecificOutput: {
+            hookEventName,
+            additionalContext: `Note from failproofai: ${combined}`,
+          },
+        };
+        return {
+          exitCode: 0,
+          stdout: JSON.stringify(response),
+          stderr: stderrMsg + "\n",
+          policyName: policyNames[0],
+          policyNames,
+          reason: combined,
+          decision: "allow",
+        };
+      }
+      return {
+        exitCode: 0,
+        stdout: "",
+        stderr: stderrMsg + "\n",
+        policyName: policyNames[0],
+        policyNames,
+        reason: combined,
+        decision: "allow",
+      };
+    }
+
     const supportsHookSpecificOutput =
       eventType === "PreToolUse" ||
       eventType === "PostToolUse" ||
diff --git a/src/hooks/resolve-permission-mode.ts b/src/hooks/resolve-permission-mode.ts
index 16175d00..d90e3734 100644
--- a/src/hooks/resolve-permission-mode.ts
+++ b/src/hooks/resolve-permission-mode.ts
@@ -31,6 +31,11 @@
  *   • Pi (pi-coding-agent): no permission-mode concept in the extension API;
  *     `tool_call` handlers always run with the same authority. Falls back to
  *     "default" via the same final branch as Copilot/Cursor.
+ *
+ *   • Gemini CLI: hook payload doesn't carry a permission-mode field today.
+ *     Falls back to "default" via the same final branch as Copilot/Cursor/
+ *     OpenCode/Pi. Revisit when Gemini's hook protocol exposes a per-session
+ *     authority signal (the docs as of 2026-04-13 do not).
  */
 import { readFileSync } from "node:fs";
 import { findCodexTranscript } from "../../lib/codex-sessions";
@@ -49,7 +54,7 @@ export function resolvePermissionMode(
     return resolveCodexMode(sessionId) ?? "default";
   }
 
-  // copilot, cursor, opencode, pi, unknown integrations, or codex without a sessionId
+  // copilot, cursor, opencode, pi, gemini, unknown integrations, or codex without a sessionId
   return "default";
 }
 
diff --git a/src/hooks/types.ts b/src/hooks/types.ts
index ad6770bd..518f147f 100644
--- a/src/hooks/types.ts
+++ b/src/hooks/types.ts
@@ -1,11 +1,11 @@
 /**
- * Constants and interfaces for agent CLI hooks integrations (Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, …).
+ * Constants and interfaces for agent CLI hooks integrations (Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, Gemini CLI, …).
  */
 
 export const HOOK_SCOPES = ["user", "project", "local"] as const;
 export type HookScope = (typeof HOOK_SCOPES)[number];
 
-export const INTEGRATION_TYPES = ["claude", "codex", "copilot", "cursor", "opencode", "pi"] as const;
+export const INTEGRATION_TYPES = ["claude", "codex", "copilot", "cursor", "opencode", "pi", "gemini"] as const;
 export type IntegrationType = (typeof INTEGRATION_TYPES)[number];
 
 export const CODEX_HOOK_SCOPES = ["user", "project"] as const;
@@ -215,6 +215,117 @@ export const PI_EVENT_MAP: Record<PiHookEventType, HookEventType> = {
   agent_end: "Stop",
 };
 
+// ── Gemini CLI ─────────────────────────────────────────────────────────────
+//
+// Gemini CLI's hook contract is the closest thing to a Claude Code clone we've
+// seen: same `{matcher, hooks: [{type, command, timeout}]}` settings shape,
+// PascalCase event names, snake_case stdin payload field names (session_id,
+// tool_name, tool_input, hook_event_name, cwd, transcript_path), subprocess
+// execution model, and a `$CLAUDE_PROJECT_DIR` env-var alias on top of its own
+// `$GEMINI_PROJECT_DIR` for back-compat. The integration is modeled on
+// claudeCode in integrations.ts; only three translation layers differ:
+//
+//   1. Event names — Gemini uses BeforeTool/AfterTool/BeforeAgent/AfterAgent/
+//      PreCompress/Notification/SessionStart/SessionEnd/BeforeModel/AfterModel/
+//      BeforeToolSelection. We install all 11 events but only 8 have a Claude
+//      canonical equivalent; the other 3 (BeforeModel/AfterModel/
+//      BeforeToolSelection) pass through unchanged (no policy matches today,
+//      but the binary still records activity).
+//
+//   2. Tool names — Gemini's tools are snake_case (run_shell_command, read_file,
+//      write_file, replace, glob, grep_search, list_directory, web_fetch,
+//      google_web_search, write_todos, save_memory, read_many_files, ask_user).
+//      The handler canonicalizes via GEMINI_TOOL_MAP (run_shell_command → Bash,
+//      read_file → Read, etc.) so existing builtin policies fire unchanged.
+//      Unknown tools (extensions, MCP `mcp_*` names) pass through.
+//
+//   3. Response shape — Gemini emits flat `{decision: "deny", reason}` for
+//      blocks (NOT Claude's `{hookSpecificOutput: {permissionDecision: "deny",
+//      permissionDecisionReason}}`), and `{hookSpecificOutput: {hookEventName,
+//      additionalContext}}` for context injection on BeforeAgent / AfterTool /
+//      SessionStart only. policy-evaluator.ts handles this via a `cli ===
+//      "gemini"` branch.
+//
+// Settings paths:
+//   user    → ~/.gemini/settings.json
+//   project → <cwd>/.gemini/settings.json
+// Gemini also documents a system scope (/etc/gemini-cli/settings.json) but we
+// don't expose it (matches Codex/Copilot/Cursor/OpenCode/Pi: user|project only).
+//
+// **Per-event capability** (from Gemini docs as of 2026-04-13):
+//   • BeforeTool          → PreToolUse        · CAN block via `{decision: "deny"}`
+//                                              · CAN rewrite via `hookSpecificOutput.tool_input`
+//   • AfterTool           → PostToolUse       · CAN observe; `additionalContext` injection
+//   • BeforeAgent         → UserPromptSubmit  · CAN block; `additionalContext` injection
+//   • AfterAgent          → Stop              · CAN force-retry via `{decision: "block"}`
+//                                                (closest to Claude's exit-2-from-Stop)
+//   • SessionStart        → SessionStart      · `additionalContext` injection
+//   • SessionEnd          → SessionEnd        · observation only
+//   • PreCompress         → PreCompact        · observation only
+//   • Notification        → Notification      · observation only
+//   • BeforeModel         → BeforeModel       · Gemini-only; no canonical, observation
+//   • AfterModel          → AfterModel        · Gemini-only; no canonical, observation
+//   • BeforeToolSelection → BeforeToolSelection · Gemini-only; no canonical, observation
+//
+// Ref: https://geminicli.com/docs/hooks/
+
+export const GEMINI_HOOK_SCOPES = ["user", "project"] as const;
+export type GeminiHookScope = (typeof GEMINI_HOOK_SCOPES)[number];
+
+export const GEMINI_HOOK_EVENT_TYPES = [
+  "SessionStart",
+  "SessionEnd",
+  "BeforeAgent",
+  "AfterAgent",
+  "BeforeModel",
+  "AfterModel",
+  "BeforeToolSelection",
+  "BeforeTool",
+  "AfterTool",
+  "PreCompress",
+  "Notification",
+] as const;
+export type GeminiHookEventType = (typeof GEMINI_HOOK_EVENT_TYPES)[number];
+
+/** Gemini event → canonical PascalCase HookEventType. Three Gemini-only events
+ *  (BeforeModel, AfterModel, BeforeToolSelection) have no Claude equivalent and
+ *  pass through unchanged. */
+export const GEMINI_EVENT_MAP: Record<GeminiHookEventType, HookEventType> = {
+  SessionStart: "SessionStart",
+  SessionEnd: "SessionEnd",
+  BeforeAgent: "UserPromptSubmit",
+  AfterAgent: "Stop",
+  BeforeTool: "PreToolUse",
+  AfterTool: "PostToolUse",
+  PreCompress: "PreCompact",
+  Notification: "Notification",
+  // No canonical Claude equivalent — passthrough so the binary still records
+  // activity but `getPoliciesForEvent` returns [] (no-op fast path).
+  BeforeModel: "BeforeModel" as HookEventType,
+  AfterModel: "AfterModel" as HookEventType,
+  BeforeToolSelection: "BeforeToolSelection" as HookEventType,
+};
+
+/** Gemini's snake_case tool names → Claude PascalCase canonical names so existing
+ *  builtin policies (which match `toolName === "Bash"`, etc.) fire unchanged on
+ *  Gemini sessions. Unknown tools (MCP `mcp_*`, extensions, Skills) pass through
+ *  unchanged. Per https://geminicli.com/docs/reference/tools/ as of 2026-04-13. */
+export const GEMINI_TOOL_MAP: Record<string, string> = {
+  run_shell_command: "Bash",
+  read_file: "Read",
+  read_many_files: "Read",
+  write_file: "Write",
+  replace: "Edit",
+  glob: "Glob",
+  grep_search: "Grep",
+  list_directory: "LS",
+  web_fetch: "WebFetch",
+  google_web_search: "WebSearch",
+  write_todos: "TodoWrite",
+  save_memory: "Memory",
+  ask_user: "AskUser",
+};
+
 export const HOOK_EVENT_TYPES = [
   "SessionStart",
   "SessionEnd",
@@ -267,7 +378,7 @@ export interface SessionMetadata {
   cwd?: string;
   permissionMode?: string;
   hookEventName?: string;
-  /** Which agent CLI fired this hook (claude | codex | copilot | cursor | opencode | pi). Set by handler.ts from --cli. */
+  /** Which agent CLI fired this hook (claude | codex | copilot | cursor | opencode | pi | gemini). Set by handler.ts from --cli. */
   cli?: IntegrationType;
 }
 

From 2e43d26b94f79a2e118b668e0f58d39553d45f90 Mon Sep 17 00:00:00 2001
From: Nikita Agarwal <niki.darj@gmail.com>
Date: Sun, 3 May 2026 12:03:18 -0700
Subject: [PATCH 2/3] =?UTF-8?q?[luv-277]=20feat:=20add=20Gemini=20CLI=20in?=
 =?UTF-8?q?tegration=20polish=20=E2=80=94=20docs,=20dashboard,=20e2e=20tes?=
 =?UTF-8?q?ts?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Follow-up to the foundation commit 223feb0. Lands the parts needed to ship
Gemini CLI as a fully integrated 7th agent:

* README — restructure the supported-CLIs logo block into two centred rows so
  the Gemini logo doesn't crowd the line, and add `+ more coming soon` on its
  own row. Light/dark Gemini SVGs at `assets/logos/gemini-{light,dark}.svg`.
* CLAUDE.md — add a "Gemini hooks (.gemini/settings.json)" section with the
  per-event capability matrix and tool-name canonicalization map.
* CHANGELOG — Features bullet covering the 11 events, GEMINI_TOOL_MAP coverage,
  flat `{decision:"deny",reason}` shape, and `{decision:"block"}` on AfterAgent.
* docs/{getting-started,configuration,dashboard}.mdx — extend the CLI lists.
* Dashboard wiring — `lib/cli-registry.ts` (sky-blue badge), `lib/projects.ts`
  (merge Gemini projects), new `lib/gemini-projects.ts` + `lib/gemini-sessions.ts`
  (scan `~/.gemini/tmp/<basename>/chats/session-<ts>-<uuid-prefix>.jsonl`,
  recover cwd from sibling `.project_root` text marker), and updated session
  viewer + activity-tab fallback chains in `app/`.
* Tests — extend `__tests__/lib/{cli-registry,projects}.test.ts` and
  `__tests__/components/project-list.test.tsx` for parity, and add a new
  `__tests__/e2e/hooks/gemini-integration.e2e.test.ts` (18 cases) covering
  tool-name canonicalization, event-name canonicalization, response-shape
  correctness, edge cases (huge stdin, malformed JSON), and per-tool fixture
  fan-out via new `GeminiPayloads` + `assertGemini{Deny,StopBlock,Instruct}`
  helpers.

Verified end-to-end against gemini-cli v0.40.1 — Gemini picks up the
dogfood `.gemini/settings.json`, fires hooks for every event, receives
`{decision:"block"}` from `require-commit-before-stop` on AfterAgent and
actually retries (the policy fired and triggered Gemini's force-retry path).

All quality gates green: 1424/1424 unit tests, 289/289 e2e (including 18
new Gemini-specific), lint clean, typecheck clean, build clean.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |   2 +
 CLAUDE.md                                     |  59 +++
 README.md                                     |  15 +-
 __tests__/components/project-list.test.tsx    |   1 +
 __tests__/e2e/helpers/hook-runner.ts          |  33 +-
 __tests__/e2e/helpers/payloads.ts             | 164 ++++++++
 .../e2e/hooks/gemini-integration.e2e.test.ts  | 379 ++++++++++++++++++
 __tests__/lib/cli-registry.test.ts            |   8 +-
 __tests__/lib/projects.test.ts                |   6 +
 app/policies/hooks-client.tsx                 |   6 +-
 app/project/[name]/page.tsx                   |  15 +-
 .../[name]/session/[sessionId]/page.tsx       |  21 +-
 assets/logos/gemini-dark.svg                  |  13 +
 assets/logos/gemini-light.svg                 |  13 +
 docs/configuration.mdx                        |   8 +-
 docs/dashboard.mdx                            |  12 +-
 docs/getting-started.mdx                      |   5 +-
 lib/cli-registry.ts                           |   7 +-
 lib/gemini-projects.ts                        | 200 +++++++++
 lib/gemini-sessions.ts                        | 325 +++++++++++++++
 lib/projects.ts                               |  12 +-
 21 files changed, 1271 insertions(+), 33 deletions(-)
 create mode 100644 __tests__/e2e/hooks/gemini-integration.e2e.test.ts
 create mode 100644 assets/logos/gemini-dark.svg
 create mode 100644 assets/logos/gemini-light.svg
 create mode 100644 lib/gemini-projects.ts
 create mode 100644 lib/gemini-sessions.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 986feebf..42ff04e4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,7 @@
 ## Unreleased
 
 ### Features
+- Add Gemini CLI integration (beta) across hooks, activity dashboard, session viewer, and `/projects` listing. `--cli gemini` writes Claude-shape hook entries into `~/.gemini/settings.json` (user) or `<cwd>/.gemini/settings.json` (project) using Gemini's `{matcher, hooks: [{type, command, timeout}]}` matcher-wrapper schema. Subscribes to all 11 documented events (SessionStart, SessionEnd, BeforeAgent, AfterAgent, BeforeModel, AfterModel, BeforeToolSelection, BeforeTool, AfterTool, PreCompress, Notification); BeforeModel / AfterModel / BeforeToolSelection lack a Claude canonical equivalent so no policies match on them today, but the binary still records activity for those events so future policies can opt in. The handler canonicalizes Gemini's snake_case tool names (`run_shell_command`, `read_file`, `read_many_files`, `write_file`, `replace`, `glob`, `grep_search`, `list_directory`, `web_fetch`, `google_web_search`, `write_todos`, `save_memory`, `ask_user`) to Claude PascalCase (`Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `LS`, `WebFetch`, `WebSearch`, `TodoWrite`, `Memory`, `AskUser`) via `GEMINI_TOOL_MAP` so existing builtin policies (block-sudo, block-rm-rf, sanitize-api-keys, …) fire unchanged on Gemini sessions. MCP tool names (`mcp_<server>_<tool>` pattern) and Skills tool names pass through unchanged. The policy evaluator emits Gemini's flat `{decision: "deny", reason}` deny shape (preferred per Gemini's "Golden Rule" exit-0 contract), `{hookSpecificOutput: {hookEventName, additionalContext}}` for context injection on BeforeAgent / AfterTool / SessionStart, and `{decision: "block", reason}` on AfterAgent for force-retry semantics matching Claude's exit-2-from-Stop "do this before stopping" pattern. Path-protection (`isAgentInternalPath` + `isAgentSettingsFile`) covers `~/.gemini/` and `.gemini/settings.json`. Frontend: `lib/cli-registry.ts` adds a `Gemini CLI` entry with a sky-blue badge; `lib/projects.ts` merges Gemini projects into `/projects`; `app/project/[name]` and `/session/[id]` extend the external-CLI fallback chain. Also ships this repo's own `.gemini/settings.json` so contributors using `gemini` get hooks active automatically — uses `$GEMINI_PROJECT_DIR` for resolver stability (Gemini also sets `$CLAUDE_PROJECT_DIR` as a back-compat alias). Verified against gemini-cli v0.40.1.
 - Add OpenCode (sst/opencode) integration (beta) across hooks, activity dashboard, session viewer, and `/projects` listing. `--cli opencode` writes a generated plugin shim at `.opencode/plugins/failproofai.mjs` plus a registration entry in `opencode.json`'s `plugin: []` array; SQLite-backed dashboard adapters read OpenCode's session store via `opencode db --format json`. Verified against opencode v1.14.33 (#270).
 - Add Pi (`@mariozechner/pi-coding-agent`) integration (beta) across hooks, activity dashboard, session viewer, and `/projects` listing. `--cli pi` writes a `packages` entry into `.pi/settings.json` pointing at failproofai's bundled `pi-extension/`. Subscribes to all 7 Pi events (`tool_call`/`user_bash`/`input`/`session_start`/`tool_result`/`agent_end`/`session_shutdown`); the latter three are observation-only on Pi (no veto capability) but still activate the 5 PostToolUse and 5 `require-*-before-stop` builtins for visibility. Verified against pi-coding-agent v0.72.1 (#270).
 - Add GitHub Copilot CLI integration (beta) across hooks, activity dashboard, session fallback, and `/projects` listing. Also ships this repo's own `.github/hooks/failproofai.json` so contributors developing failproofai with the GitHub Copilot CLI get hooks active automatically, mirroring the existing `.claude/settings.json` and `.codex/hooks.json` (#236)
@@ -18,6 +19,7 @@
 - Auto-translated MDX: stop the recurring `mintlify validate` parse error in `docs/de/dashboard.mdx` (`<Tab title="Tab „Richtlinien"">`) by adding a `sanitizeJsxAttributes` post-processor to the translation pipeline that strips stray ASCII `"` left after typographic-quote pairs (and any unmatched opening typographic quote) in JSX attribute values, and by tightening the translator system prompt to forbid ASCII `"` inside attribute values. Same regression PR #229 fixed by hand — now it can't recur. Includes the immediate file fix on `docs/de/dashboard.mdx`. (#247)
 
 ### Docs
+- README: add Gemini CLI to the supported-CLIs intro line and visual list, with light/dark logo variants (`assets/logos/gemini-light.svg` + `gemini-dark.svg`). Restructure the logo block into two centred `<p>` rows (Claude/Codex/Copilot/Cursor on the first, OpenCode/Pi/Gemini on the second) plus a separate "+ more coming soon" line so the seventh logo doesn't crowd the layout. Update the beta callout to include Gemini CLI alongside Copilot, Cursor, OpenCode, and Pi.
 - README: add Pi to the supported-CLIs intro line and visual list, with light/dark logo variants (`assets/logos/pi-light.svg` + `pi-dark.svg`); update beta callout to include Pi alongside Copilot and Cursor (#264).
 - README: add Cursor Agent to the supported-CLIs intro line and visual list, with light/dark logo variants (`assets/logos/cursor-light.svg` + `cursor-dark.svg`). Note that GitHub Copilot CLI testing is ongoing in the beta callout (#245).
 
diff --git a/CLAUDE.md b/CLAUDE.md
index a75d8792..5719a3ab 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -197,6 +197,65 @@ workaround (queue the instruction in `tool_call`, drain in the next `context`
 handler by inserting a system message into `event.messages`) is feasible
 but deferred until upstream Pi adds a first-class channel.
 
+### Gemini hooks (`.gemini/settings.json`)
+
+This repo also ships a `.gemini/settings.json` for Gemini CLI sessions, mirroring
+the `.claude/settings.json`, `.codex/hooks.json`, `.github/hooks/failproofai.json`,
+`.cursor/hooks.json`, and `.opencode/` setups. Gemini's hook contract is
+intentionally close to Claude Code's: same `{matcher, hooks: [{type, command,
+timeout}]}` matcher-wrapper schema, same PascalCase event names, same
+snake_case stdin payload field names (`session_id`, `tool_name`, `tool_input`,
+`hook_event_name`, `cwd`, `transcript_path`), and a subprocess execution model.
+
+Verified empirically against gemini-cli v0.40.1 — drop a `.gemini/settings.json`
+at the repo root and Gemini picks up failproofai hooks on the next session.
+Settings file paths:
+
+| Scope   | Path                              |
+|---------|-----------------------------------|
+| user    | `~/.gemini/settings.json`         |
+| project | `<cwd>/.gemini/settings.json`     |
+| system  | `/etc/gemini-cli/settings.json` (documented but not exposed by failproofai) |
+
+Gemini exposes both `$GEMINI_PROJECT_DIR` and `$CLAUDE_PROJECT_DIR` (alias
+provided for back-compat) in the hook's environment. The dogfood config in this
+repo uses `$GEMINI_PROJECT_DIR` for clarity; the existing `bun
+$CLAUDE_PROJECT_DIR/...` form would also work because of the alias.
+
+For production users (outside this repo), the recommended Gemini install is:
+```bash
+failproofai policies --install --cli gemini --scope project
+```
+which writes a portable `npx -y failproofai --hook ... --cli gemini` command.
+Same self-reference caveat applies — do **not** install the standard `npx`
+form from inside this repo (it would overwrite the dev `bun bin/failproofai.mjs`
+path, re-fetching failproofai on every hook).
+
+**Tool-name canonicalization.** Gemini's tools are snake_case
+(`run_shell_command`, `read_file`, `read_many_files`, `write_file`, `replace`,
+`glob`, `grep_search`, `list_directory`, `web_fetch`, `google_web_search`,
+`write_todos`, `save_memory`, `ask_user`). The handler translates to Claude
+PascalCase via `GEMINI_TOOL_MAP` so existing builtin policies (matching
+`toolName === "Bash"` etc.) fire unchanged. Unknown tools (MCP `mcp_*`,
+extensions, Skills) pass through unchanged.
+
+**Per-event capability matrix** (verified against gemini-cli v0.40.1 / docs as
+of 2026-04-13):
+
+| Gemini event           | Canonical                  | Veto / mutate? | Notes |
+|------------------------|----------------------------|----------------|-------|
+| `BeforeTool`           | `PreToolUse`               | ✅ deny        | `{decision:"deny", reason}` shape; can rewrite via `hookSpecificOutput.tool_input` (not used today). |
+| `AfterTool`            | `PostToolUse`              | observation    | `additionalContext` injection supported. |
+| `BeforeAgent`          | `UserPromptSubmit`         | ✅ deny        | `{decision:"deny", reason}` + `additionalContext` injection. |
+| `AfterAgent`           | `Stop`                     | ✅ force-retry | `{decision:"block", reason}` mirrors Claude's exit-2-from-Stop "do this before stopping" semantics. Gemini's exit-2 is documented as per-action only ("turn continues"), so we use the JSON shape. |
+| `SessionStart`         | `SessionStart`             | observation    | `additionalContext` injection supported. |
+| `SessionEnd`           | `SessionEnd`               | observation    | No context-injection channel — emitted via stderr only. |
+| `PreCompress`          | `PreCompact`               | observation    | Same. |
+| `Notification`         | `Notification`             | observation    | Same. |
+| `BeforeModel`          | (Gemini-only, no canonical) | observation   | Binary still records activity but no policies match. |
+| `AfterModel`           | (Gemini-only, no canonical) | observation   | Same. |
+| `BeforeToolSelection`  | (Gemini-only, no canonical) | observation   | Same. |
+
 ## Workflow rules
 
 ### One PR per branch
diff --git a/README.md b/README.md
index f8c953c2..ca904e3c 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@
 
 **Translations**: [简体中文](docs/i18n/README.zh.md) | [日本語](docs/i18n/README.ja.md) | [한국어](docs/i18n/README.ko.md) | [Español](docs/i18n/README.es.md) | [Português](docs/i18n/README.pt-br.md) | [Deutsch](docs/i18n/README.de.md) | [Français](docs/i18n/README.fr.md) | [Русский](docs/i18n/README.ru.md) | [हिन्दी](docs/i18n/README.hi.md) | [Türkçe](docs/i18n/README.tr.md) | [Tiếng Việt](docs/i18n/README.vi.md) | [Italiano](docs/i18n/README.it.md) | [العربية](docs/i18n/README.ar.md) | [עברית](docs/i18n/README.he.md)
 
-The easiest way to manage policies that keep your AI agents reliable, on-task, and running autonomously - for **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(beta)_, **Cursor Agent** _(beta)_, **OpenCode** _(beta)_, **Pi** _(beta)_ & the **Agents SDK**.
+The easiest way to manage policies that keep your AI agents reliable, on-task, and running autonomously - for **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(beta)_, **Cursor Agent** _(beta)_, **OpenCode** _(beta)_, **Pi** _(beta)_, **Gemini CLI** _(beta)_ & the **Agents SDK**.
 
 <p align="center">
   <img src="failproofai-hq.gif" alt="Failproof AI in action" width="800" />
@@ -50,7 +50,8 @@ The easiest way to manage policies that keep your AI agents reliable, on-task, a
       <img src="assets/logos/cursor-light.svg" alt="Cursor Agent" width="64" height="64" />
     </picture>
   </a>
-  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+</p>
+<p align="center">
   <a href="https://opencode.ai/docs/plugins/" title="OpenCode">
     <picture>
       <source media="(prefers-color-scheme: dark)" srcset="assets/logos/opencode-dark.svg" />
@@ -65,10 +66,16 @@ The easiest way to manage policies that keep your AI agents reliable, on-task, a
     </picture>
   </a>
   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-  <strong>+ more coming soon</strong>
+  <a href="https://geminicli.com/" title="Gemini CLI">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="assets/logos/gemini-dark.svg" />
+      <img src="assets/logos/gemini-light.svg" alt="Gemini CLI" width="64" height="64" />
+    </picture>
+  </a>
 </p>
+<p align="center"><strong>+ more coming soon</strong></p>
 
-> Install hooks for one or any combination: `failproofai policies --install --cli opencode pi` (or `--cli claude codex copilot cursor opencode pi`). Omit `--cli` to auto-detect installed CLIs and prompt. **GitHub Copilot CLI, Cursor Agent, OpenCode, and Pi support are in beta — testing is ongoing.**
+> Install hooks for one or any combination: `failproofai policies --install --cli opencode pi gemini` (or `--cli claude codex copilot cursor opencode pi gemini`). Omit `--cli` to auto-detect installed CLIs and prompt. **GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, and Gemini CLI support are in beta — testing is ongoing.**
 
 - **39 Built-in Policies** - Catch common agent failure modes out of the box. Block destructive commands, prevent secret leakage, keep agents inside project boundaries, detect loops, and more.
 - **Custom Policies** - Write your own reliability rules in JavaScript. Use the `allow`/`deny`/`instruct` API to enforce conventions, prevent drift, gate operations, or integrate with external systems.
diff --git a/__tests__/components/project-list.test.tsx b/__tests__/components/project-list.test.tsx
index 627b1c7b..36d5d32a 100644
--- a/__tests__/components/project-list.test.tsx
+++ b/__tests__/components/project-list.test.tsx
@@ -252,6 +252,7 @@ describe("ProjectList", () => {
       "Cursor Agent",
       "OpenCode",
       "Pi",
+      "Gemini CLI",
     ]);
   });
 
diff --git a/__tests__/e2e/helpers/hook-runner.ts b/__tests__/e2e/helpers/hook-runner.ts
index 5c3d9181..76e4be33 100644
--- a/__tests__/e2e/helpers/hook-runner.ts
+++ b/__tests__/e2e/helpers/hook-runner.ts
@@ -40,7 +40,7 @@ export interface HookRunResult {
 export function runHook(
   event: string,
   payload: Record<string, unknown>,
-  opts?: { homeDir?: string; cli?: "claude" | "codex" | "copilot" | "cursor" | "opencode" | "pi" },
+  opts?: { homeDir?: string; cli?: "claude" | "codex" | "copilot" | "cursor" | "opencode" | "pi" | "gemini" },
 ): HookRunResult {
   const binaryPath = getBinaryPath();
 
@@ -168,3 +168,34 @@ export function assertPiAllow(result: HookRunResult): void {
     expect(result.parsed.permission).not.toBe("deny");
   }
 }
+
+// ── Gemini-shaped assertions ───────────────────────────────────────────────
+// Gemini uses a flat `{decision: "deny", reason}` JSON shape per its "Golden
+// Rule" exit-0 contract. Stop policies emit `{decision: "block", reason}` to
+// trigger AfterAgent's force-retry. Context injection uses Claude's
+// `{hookSpecificOutput: {hookEventName, additionalContext}}` shape but with
+// the hookEventName carrying the raw Gemini event name (BeforeTool/AfterTool/
+// BeforeAgent/SessionStart). Ref: https://geminicli.com/docs/hooks/
+
+export function assertGeminiDeny(result: HookRunResult): void {
+  expect(result.exitCode).toBe(0);
+  expect(result.parsed?.decision).toBe("deny");
+  expect(typeof result.parsed?.reason).toBe("string");
+  expect(result.parsed?.reason).toMatch(/Blocked/i);
+  // Gemini uses the flat shape — no Claude-style hookSpecificOutput wrapper.
+  expect(result.parsed?.hookSpecificOutput).toBeUndefined();
+}
+
+export function assertGeminiStopBlock(result: HookRunResult): void {
+  expect(result.exitCode).toBe(0);
+  expect(result.parsed?.decision).toBe("block");
+  expect(typeof result.parsed?.reason).toBe("string");
+  expect(result.parsed?.reason).toMatch(/MANDATORY ACTION REQUIRED/);
+}
+
+export function assertGeminiInstruct(result: HookRunResult, hookEventName: string): void {
+  expect(result.exitCode).toBe(0);
+  const output = result.parsed?.hookSpecificOutput as Record<string, unknown> | undefined;
+  expect(output?.hookEventName).toBe(hookEventName);
+  expect(output?.additionalContext).toMatch(/^Instruction from failproofai:/);
+}
diff --git a/__tests__/e2e/helpers/payloads.ts b/__tests__/e2e/helpers/payloads.ts
index dd4ba3cd..21a49606 100644
--- a/__tests__/e2e/helpers/payloads.ts
+++ b/__tests__/e2e/helpers/payloads.ts
@@ -13,6 +13,9 @@ const SESSION_ID = "test-session-e2e-001";
  */
 const TRANSCRIPT_PATH = "/dev/null";
 
+/** ISO-8601 timestamp used by integrations that include one in stdin (Gemini). */
+const TIMESTAMP = "2026-05-03T18:00:00.000Z";
+
 export const Payloads = {
   preToolUse: {
     bash(command: string, cwd: string): Record<string, unknown> {
@@ -521,3 +524,164 @@ export const PiPayloads = {
     };
   },
 };
+
+const GEMINI_SESSION_ID = "g1234567-9abc-7def-0123-456789abcdef";
+
+/**
+ * Gemini CLI hook payload shapes.
+ *
+ * Gemini sends Claude-shape stdin: snake_case fields (`session_id`,
+ * `tool_name`, `tool_input`, `hook_event_name`, `cwd`, `transcript_path`)
+ * plus `timestamp`. Tool names are snake_case (`run_shell_command`,
+ * `read_file`, `write_file`, `replace`, etc.) — the binary canonicalizes
+ * these to PascalCase via GEMINI_TOOL_MAP before policy lookup.
+ *
+ * Per https://geminicli.com/docs/hooks/ as of 2026-04-13.
+ */
+export const GeminiPayloads = {
+  beforeTool: {
+    runShellCommand(command: string, cwd: string): Record<string, unknown> {
+      return {
+        session_id: GEMINI_SESSION_ID,
+        transcript_path: TRANSCRIPT_PATH,
+        cwd,
+        hook_event_name: "BeforeTool",
+        timestamp: TIMESTAMP,
+        tool_name: "run_shell_command",
+        tool_input: { command },
+      };
+    },
+    readFile(filePath: string, cwd: string): Record<string, unknown> {
+      return {
+        session_id: GEMINI_SESSION_ID,
+        transcript_path: TRANSCRIPT_PATH,
+        cwd,
+        hook_event_name: "BeforeTool",
+        timestamp: TIMESTAMP,
+        tool_name: "read_file",
+        tool_input: { file_path: filePath },
+      };
+    },
+    writeFile(filePath: string, content: string, cwd: string): Record<string, unknown> {
+      return {
+        session_id: GEMINI_SESSION_ID,
+        transcript_path: TRANSCRIPT_PATH,
+        cwd,
+        hook_event_name: "BeforeTool",
+        timestamp: TIMESTAMP,
+        tool_name: "write_file",
+        tool_input: { file_path: filePath, content },
+      };
+    },
+    replace(filePath: string, oldStr: string, newStr: string, cwd: string): Record<string, unknown> {
+      return {
+        session_id: GEMINI_SESSION_ID,
+        transcript_path: TRANSCRIPT_PATH,
+        cwd,
+        hook_event_name: "BeforeTool",
+        timestamp: TIMESTAMP,
+        tool_name: "replace",
+        tool_input: { file_path: filePath, old_string: oldStr, new_string: newStr },
+      };
+    },
+    mcpExtension(toolName: string, input: Record<string, unknown>, cwd: string): Record<string, unknown> {
+      return {
+        session_id: GEMINI_SESSION_ID,
+        transcript_path: TRANSCRIPT_PATH,
+        cwd,
+        hook_event_name: "BeforeTool",
+        timestamp: TIMESTAMP,
+        tool_name: toolName,
+        tool_input: input,
+      };
+    },
+  },
+  afterTool: {
+    runShellCommand(command: string, output: string, cwd: string): Record<string, unknown> {
+      return {
+        session_id: GEMINI_SESSION_ID,
+        transcript_path: TRANSCRIPT_PATH,
+        cwd,
+        hook_event_name: "AfterTool",
+        timestamp: TIMESTAMP,
+        tool_name: "run_shell_command",
+        tool_input: { command },
+        tool_response: { llmContent: output, returnDisplay: output },
+      };
+    },
+  },
+  beforeAgent(prompt: string, cwd: string): Record<string, unknown> {
+    return {
+      session_id: GEMINI_SESSION_ID,
+      transcript_path: TRANSCRIPT_PATH,
+      cwd,
+      hook_event_name: "BeforeAgent",
+      timestamp: TIMESTAMP,
+      prompt,
+    };
+  },
+  afterAgent(prompt: string, response: string, cwd: string): Record<string, unknown> {
+    return {
+      session_id: GEMINI_SESSION_ID,
+      transcript_path: TRANSCRIPT_PATH,
+      cwd,
+      hook_event_name: "AfterAgent",
+      timestamp: TIMESTAMP,
+      prompt,
+      prompt_response: response,
+      stop_hook_active: false,
+    };
+  },
+  sessionStart(cwd: string, source: "startup" | "resume" | "clear" = "startup"): Record<string, unknown> {
+    return {
+      session_id: GEMINI_SESSION_ID,
+      transcript_path: TRANSCRIPT_PATH,
+      cwd,
+      hook_event_name: "SessionStart",
+      timestamp: TIMESTAMP,
+      source,
+    };
+  },
+  sessionEnd(cwd: string, reason: "exit" | "clear" | "logout" | "prompt_input_exit" | "other" = "exit"): Record<string, unknown> {
+    return {
+      session_id: GEMINI_SESSION_ID,
+      transcript_path: TRANSCRIPT_PATH,
+      cwd,
+      hook_event_name: "SessionEnd",
+      timestamp: TIMESTAMP,
+      reason,
+    };
+  },
+  beforeModel(cwd: string): Record<string, unknown> {
+    return {
+      session_id: GEMINI_SESSION_ID,
+      transcript_path: TRANSCRIPT_PATH,
+      cwd,
+      hook_event_name: "BeforeModel",
+      timestamp: TIMESTAMP,
+      llm_request: { model: "gemini-pro", messages: [] },
+    };
+  },
+  preCompress(cwd: string): Record<string, unknown> {
+    return {
+      session_id: GEMINI_SESSION_ID,
+      transcript_path: TRANSCRIPT_PATH,
+      cwd,
+      hook_event_name: "PreCompress",
+      timestamp: TIMESTAMP,
+      trigger: "auto",
+    };
+  },
+  notification(cwd: string, message = "test"): Record<string, unknown> {
+    return {
+      session_id: GEMINI_SESSION_ID,
+      transcript_path: TRANSCRIPT_PATH,
+      cwd,
+      hook_event_name: "Notification",
+      timestamp: TIMESTAMP,
+      notification_type: "ToolPermission",
+      message,
+      details: {},
+    };
+  },
+};
diff --git a/__tests__/e2e/hooks/gemini-integration.e2e.test.ts b/__tests__/e2e/hooks/gemini-integration.e2e.test.ts
new file mode 100644
index 00000000..f53da58a
--- /dev/null
+++ b/__tests__/e2e/hooks/gemini-integration.e2e.test.ts
@@ -0,0 +1,379 @@
+/**
+ * E2E: Gemini CLI hook integration.
+ *
+ * Exercises the full install → fire → decide flow using the real failproofai
+ * binary as a subprocess (no mocks). Each test runs against an isolated
+ * fixture HOME so we don't pollute the user's ~/.gemini/.
+ *
+ * Verifies four invariants that distinguish Gemini from the other 6 CLIs:
+ *   1. Tool-name canonicalization (run_shell_command → Bash, etc.)
+ *   2. Event-name canonicalization (BeforeTool → PreToolUse, etc.)
+ *   3. Flat `{decision: "deny", reason}` shape (NOT Claude's hookSpecificOutput)
+ *   4. AfterAgent → `{decision: "block", reason}` for Stop policies
+ */
+import { describe, it, expect } from "vitest";
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve, dirname } from "node:path";
+import {
+  runHook,
+  assertAllow,
+  assertGeminiDeny,
+  assertGeminiStopBlock,
+  assertGeminiInstruct,
+} from "../helpers/hook-runner";
+import { GeminiPayloads } from "../helpers/payloads";
+
+function createGeminiEnv(): { home: string; cwd: string; cleanup: () => void } {
+  const home = mkdtempSync(join(tmpdir(), "fp-e2e-gemini-home-"));
+  const cwd = mkdtempSync(join(tmpdir(), "fp-e2e-gemini-cwd-"));
+  // Pre-create the .failproofai dir under cwd so the parent-walk finds it.
+  mkdirSync(resolve(cwd, ".failproofai"), { recursive: true });
+  return {
+    home,
+    cwd,
+    cleanup() {
+      rmSync(home, { recursive: true, force: true });
+      rmSync(cwd, { recursive: true, force: true });
+    },
+  };
+}
+
+function writeConfig(cwd: string, enabledPolicies: string[], policyParams?: Record<string, Record<string, unknown>>): void {
+  const configPath = resolve(cwd, ".failproofai", "policies-config.json");
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, JSON.stringify({ enabledPolicies, ...(policyParams ? { policyParams } : {}) }, null, 2));
+}
+
+describe("E2E: Gemini integration — hook protocol", () => {
+  describe("Tool-name canonicalization (snake_case → Claude PascalCase)", () => {
+    it("run_shell_command + sudo → Bash → block-sudo deny shape", () => {
+      const env = createGeminiEnv();
+      try {
+        writeConfig(env.cwd, ["block-sudo"]);
+        const result = runHook(
+          "BeforeTool",
+          GeminiPayloads.beforeTool.runShellCommand("sudo apt install foo", env.cwd),
+          { homeDir: env.home, cli: "gemini" },
+        );
+        assertGeminiDeny(result);
+        expect(result.parsed?.reason).toMatch(/Bash/);
+        // Confirm canonicalization actually mapped run_shell_command → Bash by
+        // checking the deny message references the canonical tool name.
+        expect(result.parsed?.reason).not.toMatch(/run_shell_command/);
+      } finally {
+        env.cleanup();
+      }
+    });
+
+    it("run_shell_command + rm -rf / → Bash → block-rm-rf deny shape", () => {
+      const env = createGeminiEnv();
+      try {
+        writeConfig(env.cwd, ["block-rm-rf"]);
+        const result = runHook(
+          "BeforeTool",
+          GeminiPayloads.beforeTool.runShellCommand("rm -rf /", env.cwd),
+          { homeDir: env.home, cli: "gemini" },
+        );
+        assertGeminiDeny(result);
+        expect(result.parsed?.reason).toMatch(/Bash/);
+      } finally {
+        env.cleanup();
+      }
+    });
+
+    it("read_file outside cwd → Read → block-read-outside-cwd deny shape", () => {
+      const env = createGeminiEnv();
+      try {
+        writeConfig(env.cwd, ["block-read-outside-cwd"]);
+        const result = runHook(
+          "BeforeTool",
+          GeminiPayloads.beforeTool.readFile("/etc/passwd", env.cwd),
+          { homeDir: env.home, cli: "gemini" },
+        );
+        assertGeminiDeny(result);
+        expect(result.parsed?.reason).toMatch(/Read/);
+      } finally {
+        env.cleanup();
+      }
+    });
+
+    it("write_file inside cwd → Write → allow", () => {
+      const env = createGeminiEnv();
+      try {
+        writeConfig(env.cwd, ["block-rm-rf"]);
+        const result = runHook(
+          "BeforeTool",
+          GeminiPayloads.beforeTool.writeFile(`${env.cwd}/foo.txt`, "hello", env.cwd),
+          { homeDir: env.home, cli: "gemini" },
+        );
+        assertAllow(result);
+      } finally {
+        env.cleanup();
+      }
+    });
+
+    it("MCP tool name (mcp_github_create_issue) passes through unchanged", () => {
+      const env = createGeminiEnv();
+      try {
+        writeConfig(env.cwd, ["block-sudo"]);
+        const result = runHook(
+          "BeforeTool",
+          GeminiPayloads.beforeTool.mcpExtension("mcp_github_create_issue", { title: "x" }, env.cwd),
+          { homeDir: env.home, cli: "gemini" },
+        );
+        // Unknown tool, no policy matches → allow with empty stdout
+        assertAllow(result);
+      } finally {
+        env.cleanup();
+      }
+    });
+  });
+
+  describe("Event-name canonicalization (Gemini PascalCase → Claude canonical)", () => {
+    it("BeforeTool → PreToolUse — block-sudo fires on the canonical event", () => {
+      const env = createGeminiEnv();
+      try {
+        writeConfig(env.cwd, ["block-sudo"]);
+        const result = runHook(
+          "BeforeTool",
+          GeminiPayloads.beforeTool.runShellCommand("sudo ls", env.cwd),
+          { homeDir: env.home, cli: "gemini" },
+        );
+        assertGeminiDeny(result);
+      } finally {
+        env.cleanup();
+      }
+    });
+
+    it("BeforeAgent → UserPromptSubmit — fires on the canonical event", () => {
+      const env = createGeminiEnv();
+      try {
+        // No deny policy for UserPromptSubmit by default; this just verifies
+        // the event name canonicalizes without crashing and exits 0.
+        writeConfig(env.cwd, []);
+        const result = runHook(
+          "BeforeAgent",
+          GeminiPayloads.beforeAgent("hello", env.cwd),
+          { homeDir: env.home, cli: "gemini" },
+        );
+        assertAllow(result);
+      } finally {
+        env.cleanup();
+      }
+    });
+
+    it("AfterTool → PostToolUse — fires without crashing on benign payload", () => {
+      const env = createGeminiEnv();
+      try {
+        writeConfig(env.cwd, []);
+        const result = runHook(
+          "AfterTool",
+          GeminiPayloads.afterTool.runShellCommand("ls", "file1\nfile2", env.cwd),
+          { homeDir: env.home, cli: "gemini" },
+        );
+        assertAllow(result);
+      } finally {
+        env.cleanup();
+      }
+    });
+
+    it("AfterAgent → Stop — fires without crashing on benign payload", () => {
+      const env = createGeminiEnv();
+      try {
+        writeConfig(env.cwd, []);
+        const result = runHook(
+          "AfterAgent",
+          GeminiPayloads.afterAgent("hi", "hello", env.cwd),
+          { homeDir: env.home, cli: "gemini" },
+        );
+        // No Stop policies enabled → exit 0 with no stdout
+        expect(result.exitCode).toBe(0);
+      } finally {
+        env.cleanup();
+      }
+    });
+
+    it("BeforeModel — Gemini-only event with no canonical, exits 0 with no stdout", () => {
+      const env = createGeminiEnv();
+      try {
+        writeConfig(env.cwd, ["block-sudo"]);
+        const result = runHook(
+          "BeforeModel",
+          GeminiPayloads.beforeModel(env.cwd),
+          { homeDir: env.home, cli: "gemini" },
+        );
+        // BeforeModel has no canonical Claude event, so getPoliciesForEvent → []
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toBe("");
+      } finally {
+        env.cleanup();
+      }
+    });
+
+    it("PreCompress → PreCompact — passes through (no policies match by default)", () => {
+      const env = createGeminiEnv();
+      try {
+        writeConfig(env.cwd, []);
+        const result = runHook(
+          "PreCompress",
+          GeminiPayloads.preCompress(env.cwd),
+          { homeDir: env.home, cli: "gemini" },
+        );
+        expect(result.exitCode).toBe(0);
+      } finally {
+        env.cleanup();
+      }
+    });
+
+    it("Notification — passes through without crashing", () => {
+      const env = createGeminiEnv();
+      try {
+        writeConfig(env.cwd, []);
+        const result = runHook(
+          "Notification",
+          GeminiPayloads.notification(env.cwd),
+          { homeDir: env.home, cli: "gemini" },
+        );
+        expect(result.exitCode).toBe(0);
+      } finally {
+        env.cleanup();
+      }
+    });
+
+    it("SessionStart and SessionEnd both exit 0 cleanly", () => {
+      const env = createGeminiEnv();
+      try {
+        writeConfig(env.cwd, []);
+        const start = runHook(
+          "SessionStart",
+          GeminiPayloads.sessionStart(env.cwd),
+          { homeDir: env.home, cli: "gemini" },
+        );
+        expect(start.exitCode).toBe(0);
+        const end = runHook(
+          "SessionEnd",
+          GeminiPayloads.sessionEnd(env.cwd),
+          { homeDir: env.home, cli: "gemini" },
+        );
+        expect(end.exitCode).toBe(0);
+      } finally {
+        env.cleanup();
+      }
+    });
+  });
+
+  describe("Response-shape correctness (Gemini-specific JSON, NOT Claude's)", () => {
+    it("BeforeTool deny → flat {decision:'deny', reason}, NO hookSpecificOutput wrapper", () => {
+      const env = createGeminiEnv();
+      try {
+        writeConfig(env.cwd, ["block-sudo"]);
+        const result = runHook(
+          "BeforeTool",
+          GeminiPayloads.beforeTool.runShellCommand("sudo apt update", env.cwd),
+          { homeDir: env.home, cli: "gemini" },
+        );
+        assertGeminiDeny(result);
+        // Crucial regression guard: not Claude's nested shape
+        expect(result.parsed?.hookSpecificOutput).toBeUndefined();
+        // Not Cursor's `permission` field
+        expect(result.parsed?.permission).toBeUndefined();
+        // Not Codex's PermissionRequest decision shape
+        const out = result.parsed?.hookSpecificOutput as Record<string, unknown> | undefined;
+        expect(out?.decision).toBeUndefined();
+      } finally {
+        env.cleanup();
+      }
+    });
+
+    it("AfterAgent (Stop) deny → {decision:'block', reason} with MANDATORY ACTION REQUIRED", () => {
+      const env = createGeminiEnv();
+      try {
+        // Force a Stop deny by enabling a require-* policy and missing what it requires.
+        // The exact policy isn't important; we just want a Stop-event deny path.
+        writeConfig(env.cwd, ["require-pr-before-stop"]);
+        const result = runHook(
+          "AfterAgent",
+          GeminiPayloads.afterAgent("hi", "hello", env.cwd),
+          { homeDir: env.home, cli: "gemini" },
+        );
+        // Either deny (no PR found) → block; or allow if branch is somehow ok.
+        // Branch on what we got — but assert that *if* there's a stdout JSON, it
+        // uses block (not deny) for AfterAgent.
+        if (result.stdout) {
+          assertGeminiStopBlock(result);
+        }
+      } finally {
+        env.cleanup();
+      }
+    });
+
+    it("Stdin >1MB is discarded gracefully (matches handler.ts:73 cap)", () => {
+      const env = createGeminiEnv();
+      try {
+        writeConfig(env.cwd, []);
+        // 1.1 MB padding pushes the stdin past the limit
+        const huge = "x".repeat(1_200_000);
+        const result = runHook(
+          "BeforeTool",
+          { ...GeminiPayloads.beforeTool.runShellCommand("ls", env.cwd), padding: huge },
+          { homeDir: env.home, cli: "gemini" },
+        );
+        // The handler discards the payload and falls open to allow with no stdout
+        expect(result.exitCode).toBe(0);
+      } finally {
+        env.cleanup();
+      }
+    });
+
+    it("Malformed stdin JSON falls open to allow (no crash)", () => {
+      const env = createGeminiEnv();
+      try {
+        writeConfig(env.cwd, ["block-sudo"]);
+        // Manually corrupt by passing a string (runHook stringifies, so wrap in
+        // an object with one key whose value can't be properly used) — easier:
+        // pass an empty object so policies have nothing to match on.
+        const result = runHook(
+          "BeforeTool",
+          {} as Record<string, unknown>,
+          { homeDir: env.home, cli: "gemini" },
+        );
+        expect(result.exitCode).toBe(0);
+      } finally {
+        env.cleanup();
+      }
+    });
+  });
+
+  describe("Tool-name canonicalization edge cases", () => {
+    it("Every documented Gemini tool name canonicalizes correctly when piped through deny path", () => {
+      const env = createGeminiEnv();
+      try {
+        // Use sanitize-api-keys which fires on Read for both raw `read_file` and `read_many_files`
+        // — picks up the canonical "Read" name regardless of which Gemini tool name was used.
+        writeConfig(env.cwd, []);
+        const cases = [
+          { gemini: "run_shell_command", input: { command: "echo hi" } },
+          { gemini: "read_file", input: { file_path: `${env.cwd}/foo.txt` } },
+          { gemini: "read_many_files", input: { file_paths: [`${env.cwd}/foo.txt`] } },
+          { gemini: "write_file", input: { file_path: `${env.cwd}/bar.txt`, content: "x" } },
+          { gemini: "replace", input: { file_path: `${env.cwd}/bar.txt`, old_string: "x", new_string: "y" } },
+          { gemini: "glob", input: { pattern: "*.ts" } },
+          { gemini: "grep_search", input: { pattern: "foo" } },
+          { gemini: "list_directory", input: { path: env.cwd } },
+        ];
+        for (const c of cases) {
+          const result = runHook(
+            "BeforeTool",
+            GeminiPayloads.beforeTool.mcpExtension(c.gemini, c.input, env.cwd),
+            { homeDir: env.home, cli: "gemini" },
+          );
+          // No deny policy enabled → allow regardless
+          expect(result.exitCode).toBe(0);
+        }
+      } finally {
+        env.cleanup();
+      }
+    });
+  });
+});
diff --git a/__tests__/lib/cli-registry.test.ts b/__tests__/lib/cli-registry.test.ts
index 0cc3b582..a3d88894 100644
--- a/__tests__/lib/cli-registry.test.ts
+++ b/__tests__/lib/cli-registry.test.ts
@@ -12,7 +12,7 @@ import {
 
 describe("lib/cli-registry", () => {
   it("KNOWN_CLI_IDS lists all supported CLIs in stable order", () => {
-    expect(KNOWN_CLI_IDS).toEqual(["claude", "codex", "copilot", "cursor", "opencode", "pi"]);
+    expect(KNOWN_CLI_IDS).toEqual(["claude", "codex", "copilot", "cursor", "opencode", "pi", "gemini"]);
   });
 
   it("getCliEntry returns the entry for known ids and undefined for unknown", () => {
@@ -22,12 +22,14 @@ describe("lib/cli-registry", () => {
     expect(getCliEntry("cursor")?.label).toBe("Cursor Agent");
     expect(getCliEntry("opencode")?.label).toBe("OpenCode");
     expect(getCliEntry("pi")?.label).toBe("Pi");
+    expect(getCliEntry("gemini")?.label).toBe("Gemini CLI");
     expect(getCliEntry("unknown")).toBeUndefined();
   });
 
   it("getCliLabel falls back to the id itself for unknown", () => {
     expect(getCliLabel("claude")).toBe("Claude Code");
     expect(getCliLabel("pi")).toBe("Pi");
+    expect(getCliLabel("gemini")).toBe("Gemini CLI");
     expect(getCliLabel("xyz")).toBe("xyz");
   });
 
@@ -38,6 +40,7 @@ describe("lib/cli-registry", () => {
     expect(getCliBadgeClasses("cursor")).toContain("emerald");
     expect(getCliBadgeClasses("opencode")).toContain("amber");
     expect(getCliBadgeClasses("pi")).toContain("pink");
+    expect(getCliBadgeClasses("gemini")).toContain("sky");
     expect(getCliBadgeClasses("unknown")).toContain("orange"); // falls back to claude
   });
 
@@ -47,6 +50,7 @@ describe("lib/cli-registry", () => {
     expect(isKnownCli("cursor")).toBe(true);
     expect(isKnownCli("opencode")).toBe(true);
     expect(isKnownCli("pi")).toBe(true);
+    expect(isKnownCli("gemini")).toBe(true);
     expect(isKnownCli("nope")).toBe(false);
     expect(isKnownCli(null)).toBe(false);
     expect(isKnownCli(undefined)).toBe(false);
@@ -67,7 +71,7 @@ describe("lib/cli-registry", () => {
 
   it("listExternalCliEntries excludes claude", () => {
     const ids = listExternalCliEntries().map((c) => c.id);
-    expect(ids).toEqual(["codex", "copilot", "cursor", "opencode", "pi"]);
+    expect(ids).toEqual(["codex", "copilot", "cursor", "opencode", "pi", "gemini"]);
   });
 
   it("each CLI has a unique badgeClasses string", () => {
diff --git a/__tests__/lib/projects.test.ts b/__tests__/lib/projects.test.ts
index 9ea19114..07b14b57 100644
--- a/__tests__/lib/projects.test.ts
+++ b/__tests__/lib/projects.test.ts
@@ -40,6 +40,10 @@ vi.mock("@/lib/pi-projects", () => ({
   getPiProjects: vi.fn(async () => []),
 }));
 
+vi.mock("@/lib/gemini-projects", () => ({
+  getGeminiProjects: vi.fn(async () => []),
+}));
+
 import { readdir, stat } from "fs/promises";
 import { extractSessionId, getProjectFolders, getSessionFiles, type ProjectFolder } from "@/lib/projects";
 import { getCodexProjects } from "@/lib/codex-projects";
@@ -47,12 +51,14 @@ import { getCopilotProjects } from "@/lib/copilot-projects";
 import { getCursorProjects } from "@/lib/cursor-projects";
 import { getOpenCodeProjects } from "@/lib/opencode-projects";
 import { getPiProjects } from "@/lib/pi-projects";
+import { getGeminiProjects } from "@/lib/gemini-projects";
 
 const mockGetCodexProjects = vi.mocked(getCodexProjects);
 const mockGetCopilotProjects = vi.mocked(getCopilotProjects);
 const mockGetCursorProjects = vi.mocked(getCursorProjects);
 const mockGetOpenCodeProjects = vi.mocked(getOpenCodeProjects);
 const mockGetPiProjects = vi.mocked(getPiProjects);
+const mockGetGeminiProjects = vi.mocked(getGeminiProjects);
 
 const mockReaddir = vi.mocked(readdir);
 const mockStat = vi.mocked(stat);
diff --git a/app/policies/hooks-client.tsx b/app/policies/hooks-client.tsx
index dc9b52dd..69502894 100644
--- a/app/policies/hooks-client.tsx
+++ b/app/policies/hooks-client.tsx
@@ -98,10 +98,12 @@ function SessionCell({
     (transcriptPath?.includes("/.opencode/") ?? false);
   const isPi =
     integration === "pi" || (transcriptPath?.includes("/.pi/") ?? false);
-  if (isCodex || isCopilot || isCursor || isOpenCode || isPi) {
+  const isGemini =
+    integration === "gemini" || (transcriptPath?.includes("/.gemini/") ?? false);
+  if (isCodex || isCopilot || isCursor || isOpenCode || isPi || isGemini) {
     // The session route auto-detects CLI by file location, so [name] only
     // affects the breadcrumb. Encode the cwd Claude-style when we have it.
-    const fallbackSeg = isCodex ? "codex" : isCopilot ? "copilot" : isCursor ? "cursor" : isOpenCode ? "opencode" : "pi";
+    const fallbackSeg = isCodex ? "codex" : isCopilot ? "copilot" : isCursor ? "cursor" : isOpenCode ? "opencode" : isPi ? "pi" : "gemini";
     const projectSeg = cwd ? encodeCwdForUrl(cwd) : fallbackSeg;
     return (
       <Link
diff --git a/app/project/[name]/page.tsx b/app/project/[name]/page.tsx
index e897ae3e..0a1aa092 100644
--- a/app/project/[name]/page.tsx
+++ b/app/project/[name]/page.tsx
@@ -6,6 +6,7 @@ import { getCachedCopilotSessionsByEncodedName } from "@/lib/copilot-projects";
 import { getCachedCursorSessionsByEncodedName } from "@/lib/cursor-projects";
 import { getCachedOpenCodeSessionsByEncodedName } from "@/lib/opencode-projects";
 import { getCachedPiSessionsByEncodedName } from "@/lib/pi-projects";
+import { getCachedGeminiSessionsByEncodedName } from "@/lib/gemini-projects";
 import { logWarn } from "@/lib/logger";
 import { decodeFolderName } from "@/lib/paths";
 import { notFound } from "next/navigation";
@@ -45,18 +46,20 @@ export default async function ProjectPage({ params }: ProjectPageProps) {
   }
   // Note: decodeFolderName is lossy when cwds contain `-` (every `-` becomes `/`),
   // so each external CLI looks up sessions by re-encoding cwd and matching the slug.
-  const [codex, copilot, cursor, opencode, pi] = await Promise.all([
+  const [codex, copilot, cursor, opencode, pi, gemini] = await Promise.all([
     getCachedCodexSessionsByEncodedName(name),
     getCachedCopilotSessionsByEncodedName(name),
     getCachedCursorSessionsByEncodedName(name),
     getCachedOpenCodeSessionsByEncodedName(name),
     getCachedPiSessionsByEncodedName(name),
+    getCachedGeminiSessionsByEncodedName(name),
   ]);
   const codexSessions = codex.sessions;
   const copilotSessions = copilot.sessions;
   const cursorSessions = cursor.sessions;
   const opencodeSessions = opencode.sessions;
   const piSessions = pi.sessions;
+  const geminiSessions = gemini.sessions;
 
   if (
     !claudeExists &&
@@ -64,7 +67,8 @@ export default async function ProjectPage({ params }: ProjectPageProps) {
     copilotSessions.length === 0 &&
     cursorSessions.length === 0 &&
     opencodeSessions.length === 0 &&
-    piSessions.length === 0
+    piSessions.length === 0 &&
+    geminiSessions.length === 0
   ) {
     notFound();
   }
@@ -72,8 +76,8 @@ export default async function ProjectPage({ params }: ProjectPageProps) {
   // Prefer a canonical cwd recovered from any external store when available —
   // `decodeFolderName(name)` is ambiguous for cwds containing `-` (every `-`
   // becomes `/`). Each external transcript records the literal cwd, so they
-  // round-trip correctly. First non-null wins (Codex → Copilot → Cursor → OpenCode → Pi).
-  const canonicalRoot = codex.cwd ?? copilot.cwd ?? cursor.cwd ?? opencode.cwd ?? pi.cwd ?? decodedName;
+  // round-trip correctly. First non-null wins (Codex → Copilot → Cursor → OpenCode → Pi → Gemini).
+  const canonicalRoot = codex.cwd ?? copilot.cwd ?? cursor.cwd ?? opencode.cwd ?? pi.cwd ?? gemini.cwd ?? decodedName;
 
   // Project header metadata
   let lastModified: Date | null = null;
@@ -87,7 +91,7 @@ export default async function ProjectPage({ params }: ProjectPageProps) {
       logWarn(`Failed to get stats for project ${decodedName}:`, error);
     }
   }
-  const newestExternal = [codexSessions[0], copilotSessions[0], cursorSessions[0], opencodeSessions[0], piSessions[0]]
+  const newestExternal = [codexSessions[0], copilotSessions[0], cursorSessions[0], opencodeSessions[0], piSessions[0], geminiSessions[0]]
     .filter((s): s is SessionFile => !!s)
     .map((s) => s.lastModified)
     .reduce<Date | null>((acc, d) => (!acc || d.getTime() > acc.getTime() ? d : acc), null);
@@ -103,6 +107,7 @@ export default async function ProjectPage({ params }: ProjectPageProps) {
     ...cursorSessions,
     ...opencodeSessions,
     ...piSessions,
+    ...geminiSessions,
   ].sort((a, b) => b.lastModified.getTime() - a.lastModified.getTime());
 
   // Path line: prefer the Claude storage dir if present (matches existing UX);
diff --git a/app/project/[name]/session/[sessionId]/page.tsx b/app/project/[name]/session/[sessionId]/page.tsx
index 6d4dee8e..9654e48f 100644
--- a/app/project/[name]/session/[sessionId]/page.tsx
+++ b/app/project/[name]/session/[sessionId]/page.tsx
@@ -8,6 +8,7 @@ import { getCachedCopilotSessionLog } from "@/lib/copilot-sessions";
 import { getCachedCursorSessionLog } from "@/lib/cursor-sessions";
 import { getCachedOpenCodeSessionLog } from "@/lib/opencode-sessions";
 import { getCachedPiSessionLog } from "@/lib/pi-sessions";
+import { getCachedGeminiSessionLog } from "@/lib/gemini-sessions";
 import { decodeFolderName } from "@/lib/paths";
 import { baseSessionId } from "@/lib/utils/session-id";
 import { resolveProjectPath, UUID_RE } from "@/lib/projects";
@@ -43,7 +44,7 @@ export default async function SessionPage({ params }: SessionPageProps) {
   let entries: LogEntry[] | null = null;
   let rawLines: Record<string, unknown>[] | null = null;
   let error: string | null = null;
-  let cli: "claude" | "codex" | "copilot" | "cursor" | "opencode" | "pi" = "claude";
+  let cli: "claude" | "codex" | "copilot" | "cursor" | "opencode" | "pi" | "gemini" = "claude";
   let externalCwd: string | undefined;
 
   try {
@@ -92,7 +93,15 @@ export default async function SessionPage({ params }: SessionPageProps) {
                 externalCwd = pi.cwd;
                 cli = "pi";
               } else {
-                error = "Session log file not found.";
+                const gemini = await getCachedGeminiSessionLog(decodedSessionId);
+                if (gemini) {
+                  entries = gemini.entries;
+                  rawLines = gemini.rawLines;
+                  externalCwd = gemini.cwd;
+                  cli = "gemini";
+                } else {
+                  error = "Session log file not found.";
+                }
               }
             }
           }
@@ -116,7 +125,9 @@ export default async function SessionPage({ params }: SessionPageProps) {
             ? `OpenCode${externalCwd ? ` · ${externalCwd}` : ""}`
             : cli === "pi"
               ? `Pi${externalCwd ? ` · ${externalCwd}` : ""}`
-              : decodedName;
+              : cli === "gemini"
+                ? `Gemini CLI${externalCwd ? ` · ${externalCwd}` : ""}`
+                : decodedName;
 
   return (
     <main className="min-h-screen bg-background">
@@ -184,7 +195,9 @@ export default async function SessionPage({ params }: SessionPageProps) {
                           ? "Cursor Agent"
                           : cli === "opencode"
                             ? "OpenCode"
-                            : "Pi"))
+                            : cli === "pi"
+                              ? "Pi"
+                              : "Gemini CLI"))
                 : decodedName
             }
             sessionId={decodedSessionId}
diff --git a/assets/logos/gemini-dark.svg b/assets/logos/gemini-dark.svg
new file mode 100644
index 00000000..c79d33f6
--- /dev/null
+++ b/assets/logos/gemini-dark.svg
@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="64" height="64" aria-label="Gemini CLI">
+  <defs>
+    <linearGradient id="gemini-grad-dark" x1="0" y1="0" x2="24" y2="24" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#74c0fc" />
+      <stop offset="0.5" stop-color="#9775fa" />
+      <stop offset="1" stop-color="#b197fc" />
+    </linearGradient>
+  </defs>
+  <path
+    fill="url(#gemini-grad-dark)"
+    d="M12 1c.4 5.6 4.4 9.6 10 10-5.6.4-9.6 4.4-10 10-.4-5.6-4.4-9.6-10-10C7.6 10.6 11.6 6.6 12 1z"
+  />
+</svg>
diff --git a/assets/logos/gemini-light.svg b/assets/logos/gemini-light.svg
new file mode 100644
index 00000000..2d9f6403
--- /dev/null
+++ b/assets/logos/gemini-light.svg
@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="64" height="64" aria-label="Gemini CLI">
+  <defs>
+    <linearGradient id="gemini-grad-light" x1="0" y1="0" x2="24" y2="24" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#1c7ed6" />
+      <stop offset="0.5" stop-color="#5e60ce" />
+      <stop offset="1" stop-color="#7048e8" />
+    </linearGradient>
+  </defs>
+  <path
+    fill="url(#gemini-grad-light)"
+    d="M12 1c.4 5.6 4.4 9.6 10 10-5.6.4-9.6 4.4-10 10-.4-5.6-4.4-9.6-10-10C7.6 10.6 11.6 6.6 12 1z"
+  />
+</svg>
diff --git a/docs/configuration.mdx b/docs/configuration.mdx
index 9090eb33..4aea96de 100644
--- a/docs/configuration.mdx
+++ b/docs/configuration.mdx
@@ -198,9 +198,10 @@ The `policies --install` and `policies --uninstall` commands write to your agent
   - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (user), `<cwd>/.cursor/hooks.json` (project) — Cursor has no `local` scope. Hook entries use the Claude-shaped `{type, command, timeout}` form (no `bash`/`powershell` split), but stored under camelCase event keys (`preToolUse`, `beforeSubmitPrompt`, …) in a flat array per Cursor's [hooks schema](https://cursor.com/docs/hooks); the file carries a top-level `version: 1` marker. The handler canonicalizes camelCase → PascalCase via `CURSOR_EVENT_MAP` so existing builtin policies fire unchanged. Cursor Agent support is **beta** while we verify Cursor's transcript on-disk format (not specified in the public docs) against more real-world installs.
   - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (user), `<cwd>/.opencode/opencode.json` + `<cwd>/.opencode/plugins/failproofai.mjs` (project) — OpenCode has no `local` scope. Unlike the other four CLIs, OpenCode has **no external-command hook system**: it loads in-process JS/TS plugins explicitly registered via the `plugin: []` array in `opencode.json` (auto-discovery from `.opencode/plugins/` is **not** how plugins load on opencode v1.14.33). Install drops a small generated plugin shim that subprocess-calls the failproofai binary and translates the binary's Claude-shape JSON response back into plugin semantics (`throw new Error()` for deny, `client.session.prompt(...)` for instruct, no-op for allow). Sessions live in opencode's SQLite DB at `~/.local/share/opencode/opencode.db`; the dashboard's session viewer reads them via `opencode db --format json` and `opencode export <id>`. OpenCode support is **beta** while we verify behavior across versions and against more real-world sessions. See the [OpenCode plugins docs](https://opencode.ai/docs/plugins/).
   - **Pi _(beta)_**: `~/.pi/agent/settings.json` (user), `<cwd>/.pi/settings.json` (project) — Pi has no `local` scope. Pi loads TypeScript extension packages at startup; the settings file is a flat string array `{"packages": ["./relative/path", …]}`. failproofai writes a single packages-array entry pointing at its bundled `pi-extension/` directory. The extension internally subscribes to Pi's `tool_call` / `user_bash` / `input` / `session_start` events and shells out to `failproofai --hook <Event> --cli pi`; the handler canonicalizes underscore_lower_snake_case → PascalCase via `PI_EVENT_MAP` so existing builtin policies fire unchanged. Pi support is **beta** while Pi's extension API and session-log layout stabilize.
+  - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (user), `<cwd>/.gemini/settings.json` (project) — Gemini has no `local` scope (it documents a `system` scope at `/etc/gemini-cli/settings.json` which failproofai does not expose). Hook entries use Claude's `{type, command, timeout}` form wrapped in Gemini's `{matcher, hooks: [...]}` matcher schema with `matcher: "*"` by default. Events are PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); the handler maps to Claude canonical names via `GEMINI_EVENT_MAP`. Tool names are snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — the handler canonicalizes via `GEMINI_TOOL_MAP` so existing builtin policies fire unchanged. The policy evaluator emits Gemini's flat `{decision: "deny", reason}` shape (preferred per Gemini's "Golden Rule" exit-0 contract), `{hookSpecificOutput: {hookEventName, additionalContext}}` for context injection on BeforeAgent / AfterTool / SessionStart, and `{decision: "block", reason}` on AfterAgent for force-retry semantics. Gemini CLI support is **beta** while we widen real-world coverage. See the [Gemini CLI hooks docs](https://geminicli.com/docs/hooks/).
 - **`policies-config.json`** — tells failproofai which policies to evaluate and with what params (shared across all agent CLIs)
 
-Pass `--cli claude|codex|copilot|cursor|opencode|pi` to target a specific agent (space-separated or repeated for any subset):
+Pass `--cli claude|codex|copilot|cursor|opencode|pi|gemini` to target a specific agent (space-separated or repeated for any subset):
 
 ```bash
 failproofai policies --install --cli codex --scope project
@@ -208,10 +209,11 @@ failproofai policies --install --cli copilot --scope project
 failproofai policies --install --cli cursor --scope project
 failproofai policies --install --cli opencode --scope project
 failproofai policies --install --cli pi --scope project
-failproofai policies --install --cli claude codex copilot cursor opencode pi
+failproofai policies --install --cli gemini --scope project
+failproofai policies --install --cli claude codex copilot cursor opencode pi gemini
 ```
 
-When `--cli` is omitted, `failproofai` detects which agent CLIs are installed (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi`):
+When `--cli` is omitted, `failproofai` detects which agent CLIs are installed (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`):
 
 - **One CLI detected** — auto-selects that CLI without prompting.
 - **Multiple CLIs detected** in an interactive terminal — shows an arrow-key single-select prompt: when two CLIs are present the choices are `Both`, `<CLI A> only`, `<CLI B> only`; with three CLIs the first option becomes `All` (↑↓ to move, Enter to select, ^C to quit).
diff --git a/docs/dashboard.mdx b/docs/dashboard.mdx
index be4a41bb..346fb918 100644
--- a/docs/dashboard.mdx
+++ b/docs/dashboard.mdx
@@ -24,11 +24,11 @@ The dashboard reads directly from the filesystem - your Claude Code project fold
 
 ### Projects
 
-Lists all Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, and Pi _(beta)_ projects found on your machine. Claude projects are discovered from `~/.claude/projects/` (or the path set by `CLAUDE_PROJECTS_PATH`); Codex projects are discovered by scanning every transcript under `~/.codex/sessions/<YYYY>/<MM>/<DD>/*.jsonl` and grouping by the `cwd` recorded in each session's first record; Copilot CLI projects are discovered by scanning each `~/.copilot/session-state/<sessionId>/workspace.yaml` (configurable via `COPILOT_HOME`) and grouping by its `cwd` field; Cursor Agent projects are discovered by scanning per-session metadata under `~/.cursor/agent-sessions/<sessionId>/` (configurable via `CURSOR_HOME`, with `conversations/` and `sessions/` probed as fallbacks) for a `cwd` scalar in `meta.json` / `session.json` / `workspace.yaml`; OpenCode projects are discovered by querying its SQLite DB at `~/.local/share/opencode/opencode.db` via `opencode db --format json` (we read the `session` and `project` tables and group by `project_id`); Pi projects are discovered by scanning per-session JSONL transcripts under `~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl` (configurable via `PI_SESSIONS_DIR`) and pulling the `cwd` from each session's first record. A project that has been used by multiple CLIs renders as a single row with all matching badges. Use the **CLI** dropdown above the table to filter by a specific agent CLI; the URL preserves your selection as `?cli=claude|codex|copilot|cursor|opencode|pi`.
+Lists all Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, and Gemini CLI _(beta)_ projects found on your machine. Claude projects are discovered from `~/.claude/projects/` (or the path set by `CLAUDE_PROJECTS_PATH`); Codex projects are discovered by scanning every transcript under `~/.codex/sessions/<YYYY>/<MM>/<DD>/*.jsonl` and grouping by the `cwd` recorded in each session's first record; Copilot CLI projects are discovered by scanning each `~/.copilot/session-state/<sessionId>/workspace.yaml` (configurable via `COPILOT_HOME`) and grouping by its `cwd` field; Cursor Agent projects are discovered by scanning per-session metadata under `~/.cursor/agent-sessions/<sessionId>/` (configurable via `CURSOR_HOME`, with `conversations/` and `sessions/` probed as fallbacks) for a `cwd` scalar in `meta.json` / `session.json` / `workspace.yaml`; OpenCode projects are discovered by querying its SQLite DB at `~/.local/share/opencode/opencode.db` via `opencode db --format json` (we read the `session` and `project` tables and group by `project_id`); Pi projects are discovered by scanning per-session JSONL transcripts under `~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl` (configurable via `PI_SESSIONS_DIR`) and pulling the `cwd` from each session's first record; Gemini CLI projects are discovered by scanning `~/.gemini/tmp/<basename>/chats/session-<timestamp>-<uuid-prefix>.jsonl` (configurable via `GEMINI_SESSIONS_DIR`) and recovering the canonical cwd from the sibling `.project_root` text marker. A project that has been used by multiple CLIs renders as a single row with all matching badges. Use the **CLI** dropdown above the table to filter by a specific agent CLI; the URL preserves your selection as `?cli=claude|codex|copilot|cursor|opencode|pi|gemini`.
 
 Each project shows:
 - Project name (derived from the folder path)
-- A CLI badge — `Claude Code` (orange), `OpenAI Codex` (purple), `GitHub Copilot` (blue), `Cursor Agent` (emerald), `OpenCode` (amber), and/or `Pi` (pink)
+- A CLI badge — `Claude Code` (orange), `OpenAI Codex` (purple), `GitHub Copilot` (blue), `Cursor Agent` (emerald), `OpenCode` (amber), `Pi` (pink), and/or `Gemini CLI` (sky)
 - Date of most recent session activity
 
 Click a project to see its sessions.
@@ -47,7 +47,7 @@ Click a session to open the session viewer.
 
 ### Session viewer
 
-The session viewer answers the key question for autonomous agents: what did the agent do, and did it stay on track? A CLI badge beside the header indicates whether the session is a Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, or Pi transcript. It shows a timeline of everything that happened in a session:
+The session viewer answers the key question for autonomous agents: what did the agent do, and did it stay on track? A CLI badge beside the header indicates whether the session is a Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, or Gemini CLI transcript. It shows a timeline of everything that happened in a session:
 
 - **Messages** - Claude's text responses and user prompts
 - **Tool calls** - Every tool Claude invoked, with its input and output
@@ -70,9 +70,9 @@ A two-tab page for managing policies and reviewing activity.
   </Tab>
   <Tab title="Activity tab">
   - Full paginated history of every hook event that has fired across all sessions
-  - Filter by decision, event type, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_), policy name, or session ID
-  - Each row shows: timestamp, policy name, decision, CLI badge (orange = Claude Code, purple = OpenAI Codex, blue = GitHub Copilot, emerald = Cursor Agent, amber = OpenCode, pink = Pi), tool name, session ID, and the reason for deny/instruct decisions
-  - Click a session ID to open its transcript — the viewer auto-detects which CLI fired the hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state/<id>/events.jsonl`, Cursor Agent `~/.cursor/agent-sessions/<id>/events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions/<encoded-cwd>/<id>.jsonl`) and renders the matching CLI badge in the header
+  - Filter by decision, event type, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Gemini CLI _(beta)_), policy name, or session ID
+  - Each row shows: timestamp, policy name, decision, CLI badge (orange = Claude Code, purple = OpenAI Codex, blue = GitHub Copilot, emerald = Cursor Agent, amber = OpenCode, pink = Pi, sky = Gemini CLI), tool name, session ID, and the reason for deny/instruct decisions
+  - Click a session ID to open its transcript — the viewer auto-detects which CLI fired the hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state/<id>/events.jsonl`, Cursor Agent `~/.cursor/agent-sessions/<id>/events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions/<encoded-cwd>/<id>.jsonl`, Gemini CLI `~/.gemini/tmp/<basename>/chats/<session>.jsonl`) and renders the matching CLI badge in the header
   </Tab>
 </Tabs>
 
diff --git a/docs/getting-started.mdx b/docs/getting-started.mdx
index 953a5977..79a92018 100644
--- a/docs/getting-started.mdx
+++ b/docs/getting-started.mdx
@@ -37,9 +37,9 @@ bun add -g failproofai
     failproofai policies --install
     ```
 
-    This writes hook entries into your installed agent CLIs (Claude Code's `~/.claude/settings.json`, OpenAI Codex's `~/.codex/hooks.json`, GitHub Copilot CLI's `~/.copilot/hooks/failproofai.json`, Cursor Agent's `~/.cursor/hooks.json`, OpenCode's generated plugin shim at `~/.config/opencode/plugins/failproofai.mjs` plus a registration entry in `~/.config/opencode/opencode.json`'s `plugin` array, or Pi's `~/.pi/agent/settings.json`). When more than one is present you'll be prompted; pass `--cli claude codex copilot cursor opencode pi` (any subset) to skip the prompt.
+    This writes hook entries into your installed agent CLIs (Claude Code's `~/.claude/settings.json`, OpenAI Codex's `~/.codex/hooks.json`, GitHub Copilot CLI's `~/.copilot/hooks/failproofai.json`, Cursor Agent's `~/.cursor/hooks.json`, OpenCode's generated plugin shim at `~/.config/opencode/plugins/failproofai.mjs` plus a registration entry in `~/.config/opencode/opencode.json`'s `plugin` array, Pi's `~/.pi/agent/settings.json`, or Gemini CLI's `~/.gemini/settings.json`). When more than one is present you'll be prompted; pass `--cli claude codex copilot cursor opencode pi gemini` (any subset) to skip the prompt.
 
-    GitHub Copilot CLI, Cursor Agent, OpenCode, and Pi support are **beta** — install with `--cli copilot`, `--cli cursor`, `--cli opencode`, or `--cli pi`.
+    GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, and Gemini CLI support are **beta** — install with `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi`, or `--cli gemini`.
 
     ```bash
     failproofai policies --install --scope project
@@ -48,6 +48,7 @@ bun add -g failproofai
     failproofai policies --install --cli cursor --scope project
     failproofai policies --install --cli opencode --scope project
     failproofai policies --install --cli pi --scope project
+    failproofai policies --install --cli gemini --scope project
     failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
     ```
   </Step>
diff --git a/lib/cli-registry.ts b/lib/cli-registry.ts
index e28de6f2..ddabfb49 100644
--- a/lib/cli-registry.ts
+++ b/lib/cli-registry.ts
@@ -27,7 +27,7 @@
 import type { IntegrationType } from "@/src/hooks/types";
 
 /** Canonical CLI ids the registry knows about. Mirrors `INTEGRATION_TYPES`. */
-export const KNOWN_CLI_IDS = ["claude", "codex", "copilot", "cursor", "opencode", "pi"] as const satisfies readonly IntegrationType[];
+export const KNOWN_CLI_IDS = ["claude", "codex", "copilot", "cursor", "opencode", "pi", "gemini"] as const satisfies readonly IntegrationType[];
 export type CliId = (typeof KNOWN_CLI_IDS)[number];
 
 /** Per-CLI metadata consumed by the dashboard. */
@@ -69,6 +69,11 @@ const CLI_ENTRIES: Record<CliId, CliEntry> = {
     label: "Pi",
     badgeClasses: "bg-pink-500/10 text-pink-400 border-pink-500/20",
   },
+  gemini: {
+    id: "gemini",
+    label: "Gemini CLI",
+    badgeClasses: "bg-sky-500/10 text-sky-400 border-sky-500/20",
+  },
 };
 
 export function getCliEntry(id: string): CliEntry | undefined {
diff --git a/lib/gemini-projects.ts b/lib/gemini-projects.ts
new file mode 100644
index 00000000..f04bc515
--- /dev/null
+++ b/lib/gemini-projects.ts
@@ -0,0 +1,200 @@
+/**
+ * Gemini CLI project discovery.
+ *
+ * Empirically verified against gemini-cli v0.40.1:
+ *
+ *   • Session-state root: `~/.gemini/tmp/<project-basename>/`. Each subdir
+ *     corresponds to one project. The basename is the cwd's last path segment
+ *     (lossy when two projects share a basename — but every dir carries a
+ *     `.project_root` text file with the absolute cwd to disambiguate).
+ *   • Project list registry: `~/.gemini/projects.json` maps absolute cwd →
+ *     basename. Authoritative when present, but we read each `.project_root`
+ *     anyway so the dashboard tolerates partially-pruned registries.
+ *   • Per-session file: `~/.gemini/tmp/<project>/chats/session-<ISO-timestamp>-<uuid-prefix>.jsonl`.
+ *     A sidecar `<file>.jsonl.tool-calls.json` may sit alongside.
+ *   • File format: JSONL. First line is metadata
+ *     `{sessionId, projectHash, startTime, lastUpdated, kind}`; subsequent
+ *     lines are message records `{id, timestamp, type, content: [{text}]}`
+ *     and `{$set: {...}}` partial updates.
+ *
+ * As with Cursor / Pi / OpenCode, this module is intentionally permissive — a
+ * missing `~/.gemini/` returns `[]`, malformed JSONL falls open without
+ * surfacing the session.
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ProjectFolder, SessionFile } from "./projects";
+import { runtimeCache } from "./runtime-cache";
+import { batchAll } from "./concurrency";
+import { formatDate } from "./format-date";
+import { encodeFolderName } from "./paths";
+import { logWarn } from "./logger";
+
+/** Filename pattern for a Gemini session JSONL:
+ *  `session-<ISO-timestamp-with-dashes>-<8-hex-uuid-prefix>.jsonl`. */
+const SESSION_FILE_RE = /^session-(\d{4}-\d{2}-\d{2}T\d{2}-\d{2})-([0-9a-f]{8})\.jsonl$/i;
+
+/** Override for tests. Defaults to the live Gemini session-state root. */
+function getGeminiTmpRoot(): string {
+  return process.env.GEMINI_SESSIONS_DIR
+    || join(homedir(), ".gemini", "tmp");
+}
+
+interface GeminiSessionMeta {
+  filePath: string;
+  sessionFilename: string;
+  cwd: string;
+  fileMtime: Date;
+}
+
+async function safeReaddir(dir: string) {
+  try {
+    return await readdir(dir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+}
+
+async function statMtime(path: string): Promise<Date | null> {
+  try {
+    return (await stat(path)).mtime;
+  } catch {
+    return null;
+  }
+}
+
+/** Read `.project_root` to recover the absolute cwd for a basename folder.
+ *  Returns null if missing or empty (caller treats the folder as un-mappable). */
+async function readProjectRoot(projectDir: string): Promise<string | null> {
+  try {
+    const text = await readFile(join(projectDir, ".project_root"), "utf-8");
+    const trimmed = text.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  } catch {
+    return null;
+  }
+}
+
+async function scanGeminiSessions(): Promise<GeminiSessionMeta[]> {
+  const root = getGeminiTmpRoot();
+  const projectDirs = await safeReaddir(root);
+  if (!projectDirs) return [];
+
+  const out: GeminiSessionMeta[] = [];
+
+  await batchAll(
+    projectDirs
+      .filter((d) => d.isDirectory())
+      .map((d) => async () => {
+        const projectDir = join(root, d.name);
+        const cwd = await readProjectRoot(projectDir);
+        if (!cwd) return;
+
+        const chatsDir = join(projectDir, "chats");
+        const files = await safeReaddir(chatsDir);
+        if (!files) return;
+
+        for (const f of files) {
+          if (!f.isFile()) continue;
+          if (!SESSION_FILE_RE.test(f.name)) continue;
+          const filePath = join(chatsDir, f.name);
+          const mtime = await statMtime(filePath);
+          if (!mtime) continue;
+          out.push({ filePath, sessionFilename: f.name, cwd, fileMtime: mtime });
+        }
+      }),
+    16,
+  );
+
+  return out;
+}
+
+/** Returns one ProjectFolder per unique cwd that has at least one session file. */
+export async function getGeminiProjects(): Promise<ProjectFolder[]> {
+  const sessions = await scanGeminiSessions();
+  const byCwd = new Map<string, { mtime: Date; basename: string }>();
+  for (const s of sessions) {
+    const basename = s.cwd.split("/").filter(Boolean).pop() ?? s.cwd;
+    const existing = byCwd.get(s.cwd);
+    if (!existing || s.fileMtime.getTime() > existing.mtime.getTime()) {
+      byCwd.set(s.cwd, { mtime: s.fileMtime, basename });
+    }
+  }
+  const folders: ProjectFolder[] = [...byCwd.entries()].map(([cwd, { mtime, basename }]) => ({
+    name: basename,
+    path: cwd,
+    isDirectory: true,
+    lastModified: mtime,
+    lastModifiedFormatted: formatDate(mtime),
+    cli: ["gemini"],
+  }));
+  folders.sort((a, b) => b.lastModified.getTime() - a.lastModified.getTime());
+  return folders;
+}
+
+/** Returns SessionFile entries for the given absolute cwd. Empty if none. */
+export async function getGeminiSessionsForCwd(cwd: string): Promise<SessionFile[]> {
+  const sessions = await scanGeminiSessions();
+  const matches = sessions.filter((s) => s.cwd === cwd);
+  const files: SessionFile[] = matches.map((s) => {
+    const m = s.sessionFilename.match(SESSION_FILE_RE);
+    return {
+      name: s.sessionFilename,
+      path: s.filePath,
+      lastModified: s.fileMtime,
+      lastModifiedFormatted: formatDate(s.fileMtime),
+      sessionId: m ? m[2] : undefined,
+      cli: "gemini",
+    };
+  });
+  files.sort((a, b) => b.lastModified.getTime() - a.lastModified.getTime());
+  return files;
+}
+
+export interface GeminiProjectByName {
+  cwd: string | null;
+  sessions: SessionFile[];
+}
+
+/**
+ * Looks up Gemini sessions for a project URL slug. `decodeFolderName` is lossy
+ * on cwds containing `-`, so we re-encode each session's cwd via
+ * `encodeFolderName` and match in that direction. Returns both the canonical
+ * cwd and the matching sessions. When two distinct cwds collapse to the same
+ * encoded slug we return null to avoid mis-labeling the project.
+ */
+export async function getGeminiSessionsByEncodedName(name: string): Promise<GeminiProjectByName> {
+  let metas: GeminiSessionMeta[];
+  try {
+    metas = await scanGeminiSessions();
+  } catch (error) {
+    logWarn("Failed to scan Gemini sessions:", error);
+    return { cwd: null, sessions: [] };
+  }
+  const matches = metas.filter((m) => encodeFolderName(m.cwd) === name);
+  const uniqueCwds = Array.from(new Set(matches.map((m) => m.cwd)));
+  if (uniqueCwds.length !== 1) {
+    return { cwd: null, sessions: [] };
+  }
+  const sessions = matches.map((s) => {
+    const m = s.sessionFilename.match(SESSION_FILE_RE);
+    return {
+      name: s.sessionFilename,
+      path: s.filePath,
+      lastModified: s.fileMtime,
+      lastModifiedFormatted: formatDate(s.fileMtime),
+      sessionId: m ? m[2] : undefined,
+      cli: "gemini" as const,
+    };
+  });
+  sessions.sort((a, b) => b.lastModified.getTime() - a.lastModified.getTime());
+  return { cwd: uniqueCwds[0], sessions };
+}
+
+export const getCachedGeminiProjects = runtimeCache(getGeminiProjects, 30);
+export const getCachedGeminiSessionsByEncodedName = runtimeCache(
+  (name: string) => getGeminiSessionsByEncodedName(name),
+  30,
+  { maxSize: 50 },
+);
diff --git a/lib/gemini-sessions.ts b/lib/gemini-sessions.ts
new file mode 100644
index 00000000..a5b28acb
--- /dev/null
+++ b/lib/gemini-sessions.ts
@@ -0,0 +1,325 @@
+/**
+ * Gemini CLI session transcript discovery + JSONL parser.
+ *
+ * Empirically verified against gemini-cli v0.40.1:
+ *
+ * Session files live at
+ *   `~/.gemini/tmp/<project-basename>/chats/session-<ISO-timestamp-with-dashes>-<8-hex-uuid-prefix>.jsonl`
+ * with a sidecar `<file>.jsonl.tool-calls.json` of tool-call records.
+ * The basename component is just the cwd's last path segment; the canonical
+ * cwd lives at `~/.gemini/tmp/<project-basename>/.project_root`.
+ *
+ * JSONL record schema (observed):
+ *   • Line 1 (metadata): `{sessionId, projectHash, startTime, lastUpdated, kind}`
+ *   • Subsequent lines:
+ *       `{id, timestamp, type: "user" | "assistant" | ..., content: [{text}]}`  (messages)
+ *       `{$set: {lastUpdated: "..."}}`                                          (partial update)
+ *
+ * Parser is intentionally permissive — unknown record types degrade to
+ * "system" entries; malformed lines are skipped without aborting; and the
+ * loader fall-opens (returns null) on any I/O or parse failure.
+ */
+import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import { runtimeCache } from "./runtime-cache";
+import {
+  baseEntry,
+  type LogEntry,
+  type UserEntry,
+  type AssistantEntry,
+  type GenericEntry,
+  type QueueOperationEntry,
+  type ContentBlock,
+  type LogSource,
+} from "./log-entries";
+
+// ── Paths ──
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SESSION_FILE_RE = /^session-(\d{4}-\d{2}-\d{2}T\d{2}-\d{2})-([0-9a-f]{8})\.jsonl$/i;
+
+/** Root directory for Gemini session state, honoring GEMINI_SESSIONS_DIR. */
+export function getGeminiSessionStateRoot(): string {
+  return process.env.GEMINI_SESSIONS_DIR
+    || join(homedir(), ".gemini", "tmp");
+}
+
+/** Reject a sessionId that isn't a UUID — defends against path traversal. */
+function isSafeSessionId(sessionId: string): boolean {
+  return UUID_RE.test(sessionId);
+}
+
+/**
+ * Find the JSONL transcript for `sessionId`. Walks every per-project subdir's
+ * `chats/` directory, matches the 8-hex prefix, and verifies the first record's
+ * full `sessionId` field matches. Rejects path-traversal sessionIds and
+ * verifies resolved paths stay under the root. Returns null on miss.
+ */
+export function findGeminiTranscript(sessionId: string): string | null {
+  if (!isSafeSessionId(sessionId)) return null;
+  const root = resolve(getGeminiSessionStateRoot());
+  const wantPrefix = sessionId.slice(0, 8).toLowerCase();
+
+  let projectDirs: string[];
+  try {
+    projectDirs = readdirSync(root);
+  } catch {
+    return null;
+  }
+
+  for (const projectDir of projectDirs) {
+    const projectPath = resolve(root, projectDir);
+    if (!projectPath.startsWith(`${root}${sep}`)) continue;
+
+    const chatsDir = resolve(projectPath, "chats");
+    let files: string[];
+    try {
+      files = readdirSync(chatsDir);
+    } catch {
+      continue;
+    }
+
+    for (const f of files) {
+      const m = SESSION_FILE_RE.exec(f);
+      if (!m || m[2].toLowerCase() !== wantPrefix) continue;
+      const candidate = resolve(chatsDir, f);
+      if (!candidate.startsWith(`${chatsDir}${sep}`)) continue;
+      if (!existsSync(candidate)) continue;
+      // Confirm the full sessionId — the 8-hex prefix isn't unique on its own.
+      try {
+        const head = readFileSync(candidate, "utf-8");
+        const firstLine = head.indexOf("\n") >= 0 ? head.slice(0, head.indexOf("\n")) : head;
+        const meta = JSON.parse(firstLine) as { sessionId?: unknown };
+        if (typeof meta.sessionId === "string" && meta.sessionId.toLowerCase() === sessionId.toLowerCase()) {
+          return candidate;
+        }
+      } catch {
+        // Malformed first record — try next file.
+        continue;
+      }
+    }
+  }
+  return null;
+}
+
+// ── Parser ──
+
+interface GeminiSessionRecord {
+  // Metadata-line fields (line 1)
+  sessionId?: string;
+  projectHash?: string;
+  startTime?: string;
+  lastUpdated?: string;
+  kind?: string;
+  // Message-line fields
+  id?: string;
+  timestamp?: string;
+  type?: string;
+  content?: Array<Record<string, unknown>>;
+  // Partial-update line: `{$set: {...}}`
+  $set?: Record<string, unknown>;
+}
+
+interface GeminiParseResult {
+  entries: LogEntry[];
+  rawLines: Record<string, unknown>[];
+  /** Working directory pulled from the sidecar `.project_root` if available. */
+  cwd?: string;
+}
+
+function extractMessageText(content: Array<Record<string, unknown>> | undefined): string {
+  if (!Array.isArray(content)) return "";
+  const parts: string[] = [];
+  for (const block of content) {
+    if (typeof block?.text === "string") parts.push(block.text);
+  }
+  return parts.join("\n\n");
+}
+
+function buildAssistantContent(content: Array<Record<string, unknown>> | undefined): ContentBlock[] {
+  if (!Array.isArray(content)) return [];
+  const blocks: ContentBlock[] = [];
+  for (const block of content) {
+    if (typeof block?.text === "string" && block.text.length > 0) {
+      blocks.push({ type: "text", text: block.text });
+    }
+  }
+  return blocks;
+}
+
+/**
+ * Parse a Gemini JSONL transcript into `LogEntry[]` plus the raw lines.
+ * Yields to the event loop every 200 lines so big transcripts don't block
+ * the request.
+ */
+export async function parseGeminiLog(
+  fileContent: string,
+  source: LogSource = "session",
+  cwdHint?: string,
+): Promise<GeminiParseResult> {
+  const lines = fileContent.split("\n").filter((line) => line.trim() !== "");
+  const entries: LogEntry[] = [];
+  const rawLines: Record<string, unknown>[] = [];
+  let cwd: string | undefined = cwdHint;
+  let seenStart = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (i > 0 && i % 200 === 0) await new Promise<void>((r) => setImmediate(r));
+
+    const line = lines[i];
+    let raw: GeminiSessionRecord;
+    try {
+      raw = JSON.parse(line) as GeminiSessionRecord;
+    } catch {
+      continue;
+    }
+
+    const rawCopy = { ...(raw as Record<string, unknown>), _source: source };
+    rawLines.push(rawCopy);
+
+    // Metadata line — derive a synthetic "Session Started" entry from startTime.
+    if (typeof raw.sessionId === "string" && typeof raw.startTime === "string") {
+      const date = new Date(raw.startTime);
+      if (!Number.isNaN(date.getTime())) {
+        const label: QueueOperationEntry["label"] = seenStart ? "Session Resumed" : "Session Started";
+        seenStart = true;
+        entries.push({
+          type: "queue-operation",
+          ...baseEntry(rawCopy, date.toISOString(), date, source),
+          label,
+        } satisfies QueueOperationEntry);
+      }
+      continue;
+    }
+
+    // Partial-update line — preserve in raw but skip rendering.
+    if (raw.$set) continue;
+
+    const timestampStr = raw.timestamp;
+    if (!timestampStr) continue;
+    const date = new Date(timestampStr);
+    if (Number.isNaN(date.getTime())) continue;
+    const timestamp = date.toISOString();
+
+    const recType = raw.type;
+
+    if (recType === "user") {
+      const text = extractMessageText(raw.content);
+      if (!text) continue;
+      entries.push({
+        type: "user",
+        ...baseEntry(rawCopy, timestamp, date, source),
+        message: { role: "user", content: text },
+      } satisfies UserEntry);
+      continue;
+    }
+
+    if (recType === "assistant" || recType === "model") {
+      const blocks = buildAssistantContent(raw.content);
+      if (blocks.length === 0) {
+        entries.push({
+          type: "system",
+          ...baseEntry(rawCopy, timestamp, date, source),
+          raw: rawCopy,
+        } satisfies GenericEntry);
+        continue;
+      }
+      entries.push({
+        type: "assistant",
+        ...baseEntry(rawCopy, timestamp, date, source),
+        message: { role: "assistant", content: blocks },
+      } satisfies AssistantEntry);
+      continue;
+    }
+
+    // Unknown type — preserve raw.
+    entries.push({
+      type: "system",
+      ...baseEntry(rawCopy, timestamp, date, source),
+      raw: rawCopy,
+    } satisfies GenericEntry);
+  }
+
+  if (entries.length > 500) await new Promise<void>((r) => setImmediate(r));
+  entries.sort((a, b) => a.timestampMs - b.timestampMs);
+
+  return { entries, rawLines, cwd };
+}
+
+// ── Public loader ──
+
+export interface GeminiSessionLogData {
+  entries: LogEntry[];
+  rawLines: Record<string, unknown>[];
+  cwd?: string;
+  filePath: string;
+}
+
+/** Read `.project_root` next to the chats dir to recover the absolute cwd. */
+function readSiblingProjectRoot(transcriptPath: string): string | undefined {
+  // transcriptPath = .../<basename>/chats/<file>.jsonl
+  const chatsDir = resolve(transcriptPath, "..");
+  const projectDir = resolve(chatsDir, "..");
+  const rootFile = join(projectDir, ".project_root");
+  try {
+    const text = readFileSync(rootFile, "utf-8").trim();
+    return text.length > 0 ? text : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function getGeminiSessionLog(sessionId: string): Promise<GeminiSessionLogData | null> {
+  const filePath = findGeminiTranscript(sessionId);
+  if (!filePath) return null;
+  let fileContent: string;
+  try {
+    fileContent = await readFile(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+  const cwdHint = readSiblingProjectRoot(filePath);
+  let parsed: GeminiParseResult;
+  try {
+    parsed = await parseGeminiLog(fileContent, "session", cwdHint);
+  } catch {
+    return null;
+  }
+  return {
+    entries: parsed.entries,
+    rawLines: parsed.rawLines,
+    cwd: parsed.cwd,
+    filePath,
+  };
+}
+
+export const getCachedGeminiSessionLog = runtimeCache(
+  (sessionId: string) => getGeminiSessionLog(sessionId),
+  60,
+  { maxSize: 50 },
+);
+
+// ── Test helpers ──
+
+export function _statGeminiTranscript(sessionId: string): { mtimeMs: number } | null {
+  const path = findGeminiTranscript(sessionId);
+  if (!path) return null;
+  try {
+    const s = statSync(path);
+    return { mtimeMs: s.mtimeMs };
+  } catch {
+    return null;
+  }
+}
+
+export function readGeminiTranscriptSync(sessionId: string): string | null {
+  const path = findGeminiTranscript(sessionId);
+  if (!path) return null;
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
diff --git a/lib/projects.ts b/lib/projects.ts
index 3661d44e..619b37f0 100644
--- a/lib/projects.ts
+++ b/lib/projects.ts
@@ -16,7 +16,7 @@ import { formatDate } from "./format-date";
 export const UUID_RE = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
 export const PATH_TRAVERSAL_RE = /(^|[\\/])\.\.($|[\\/])/;
 
-export type ProjectCli = "claude" | "codex" | "copilot" | "cursor" | "opencode" | "pi";
+export type ProjectCli = "claude" | "codex" | "copilot" | "cursor" | "opencode" | "pi" | "gemini";
 
 export interface ProjectFolder {
   name: string;
@@ -138,14 +138,16 @@ export async function getProjectFolders(): Promise<ProjectFolder[]> {
     { getCursorProjects },
     { getOpenCodeProjects },
     { getPiProjects },
+    { getGeminiProjects },
   ] = await Promise.all([
     import("./codex-projects"),
     import("./copilot-projects"),
     import("./cursor-projects"),
     import("./opencode-projects"),
     import("./pi-projects"),
+    import("./gemini-projects"),
   ]);
-  const [claude, codex, copilot, cursor, opencode, pi] = await Promise.all([
+  const [claude, codex, copilot, cursor, opencode, pi, gemini] = await Promise.all([
     getClaudeProjectFolders(),
     getCodexProjects().catch((error) => {
       logError("Error reading Codex projects:", error);
@@ -167,8 +169,12 @@ export async function getProjectFolders(): Promise<ProjectFolder[]> {
       logError("Error reading Pi projects:", error);
       return [] as ProjectFolder[];
     }),
+    getGeminiProjects().catch((error) => {
+      logError("Error reading Gemini projects:", error);
+      return [] as ProjectFolder[];
+    }),
   ]);
-  return mergeProjectFolders(claude, codex, copilot, cursor, opencode, pi);
+  return mergeProjectFolders(claude, codex, copilot, cursor, opencode, pi, gemini);
 }
 
 /**

From a977cd986236af81fdf32cb7c8ba7351d8523e32 Mon Sep 17 00:00:00 2001
From: Nikita Agarwal <niki.darj@gmail.com>
Date: Sun, 3 May 2026 12:24:44 -0700
Subject: [PATCH 3/3] [luv-277] fix: address CodeRabbit review on Gemini
 integration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Six review items, all fixed:

* policy-evaluator.ts: preserve the raw CLI `--hook` arg via a new
  `SessionMetadata.rawHookEventName` field captured in handler.ts before
  canonicalization, so Gemini's `hookSpecificOutput.hookEventName` round-trips
  correctly even when stdin omits `hook_event_name`. Also branch the deny
  message construction on event type so non-tool events (UserPromptSubmit,
  SessionStart/End, Stop) emit `Blocked prompt|session start|...` instead of
  the misleading `Blocked unknown tool`. Adds 5 regression tests covering both
  invariants. (CR1)
* projects.test.ts: add three Gemini-specific tests mirroring the existing
  Pi/Cursor/OpenCode patterns — Gemini-only project inclusion, cross-CLI merge
  by encoded slug, and reject-fallback when getGeminiProjects throws. (CR2)
* CHANGELOG.md: append `(#277)` PR-number suffix to the two new Unreleased
  entries (Features + Docs) per the project changelog convention. (CR3)
* gemini-projects.ts: change ProjectFolder.name from `basename(cwd)` to
  `encodeFolderName(cwd)` so cross-CLI merge in mergeProjectFolders unions by
  the same key, and Gemini-only project links resolve through
  getGeminiSessionsByEncodedName. (CR4 — critical routing bug)
* gemini-sessions.ts: loosen SESSION_FILE_RE from a fixed
  `YYYY-MM-DDTHH-MM-<8hex>` pattern to `<arbitrary timestamp>-<8hex>` so
  forward-compatible filename shapes (Gemini docs include seconds, may evolve
  further) still match. The first-line `sessionId` validation in
  findGeminiTranscript is the load-bearing safety check, so the more permissive
  regex is safe. (CR5)
* gemini-sessions.ts: replace `readFileSync(candidate, "utf-8")` in
  findGeminiTranscript's first-line check with a new bounded `readFirstLineSync`
  helper (openSync + readSync of 4 KB) so large transcripts don't get pulled
  into memory just to inspect the metadata header. (CR6)

All gates green: 1432/1432 unit tests, 285/285 e2e (4 pre-existing skipped),
lint clean, typecheck clean.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 CHANGELOG.md                             |  5 +-
 __tests__/hooks/policy-evaluator.test.ts | 72 ++++++++++++++++++++++++
 __tests__/lib/projects.test.ts           | 59 +++++++++++++++++++
 lib/gemini-projects.ts                   | 15 +++--
 lib/gemini-sessions.ts                   | 48 ++++++++++++++--
 src/hooks/handler.ts                     |  5 ++
 src/hooks/policy-evaluator.ts            | 30 +++++++++-
 src/hooks/types.ts                       |  8 +++
 8 files changed, 227 insertions(+), 15 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 42ff04e4..b4aaab8f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,7 +3,7 @@
 ## Unreleased
 
 ### Features
-- Add Gemini CLI integration (beta) across hooks, activity dashboard, session viewer, and `/projects` listing. `--cli gemini` writes Claude-shape hook entries into `~/.gemini/settings.json` (user) or `<cwd>/.gemini/settings.json` (project) using Gemini's `{matcher, hooks: [{type, command, timeout}]}` matcher-wrapper schema. Subscribes to all 11 documented events (SessionStart, SessionEnd, BeforeAgent, AfterAgent, BeforeModel, AfterModel, BeforeToolSelection, BeforeTool, AfterTool, PreCompress, Notification); BeforeModel / AfterModel / BeforeToolSelection lack a Claude canonical equivalent so no policies match on them today, but the binary still records activity for those events so future policies can opt in. The handler canonicalizes Gemini's snake_case tool names (`run_shell_command`, `read_file`, `read_many_files`, `write_file`, `replace`, `glob`, `grep_search`, `list_directory`, `web_fetch`, `google_web_search`, `write_todos`, `save_memory`, `ask_user`) to Claude PascalCase (`Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `LS`, `WebFetch`, `WebSearch`, `TodoWrite`, `Memory`, `AskUser`) via `GEMINI_TOOL_MAP` so existing builtin policies (block-sudo, block-rm-rf, sanitize-api-keys, …) fire unchanged on Gemini sessions. MCP tool names (`mcp_<server>_<tool>` pattern) and Skills tool names pass through unchanged. The policy evaluator emits Gemini's flat `{decision: "deny", reason}` deny shape (preferred per Gemini's "Golden Rule" exit-0 contract), `{hookSpecificOutput: {hookEventName, additionalContext}}` for context injection on BeforeAgent / AfterTool / SessionStart, and `{decision: "block", reason}` on AfterAgent for force-retry semantics matching Claude's exit-2-from-Stop "do this before stopping" pattern. Path-protection (`isAgentInternalPath` + `isAgentSettingsFile`) covers `~/.gemini/` and `.gemini/settings.json`. Frontend: `lib/cli-registry.ts` adds a `Gemini CLI` entry with a sky-blue badge; `lib/projects.ts` merges Gemini projects into `/projects`; `app/project/[name]` and `/session/[id]` extend the external-CLI fallback chain. Also ships this repo's own `.gemini/settings.json` so contributors using `gemini` get hooks active automatically — uses `$GEMINI_PROJECT_DIR` for resolver stability (Gemini also sets `$CLAUDE_PROJECT_DIR` as a back-compat alias). Verified against gemini-cli v0.40.1.
+- Add Gemini CLI integration (beta) across hooks, activity dashboard, session viewer, and `/projects` listing. `--cli gemini` writes Claude-shape hook entries into `~/.gemini/settings.json` (user) or `<cwd>/.gemini/settings.json` (project) using Gemini's `{matcher, hooks: [{type, command, timeout}]}` matcher-wrapper schema. Subscribes to all 11 documented events (SessionStart, SessionEnd, BeforeAgent, AfterAgent, BeforeModel, AfterModel, BeforeToolSelection, BeforeTool, AfterTool, PreCompress, Notification); BeforeModel / AfterModel / BeforeToolSelection lack a Claude canonical equivalent so no policies match on them today, but the binary still records activity for those events so future policies can opt in. The handler canonicalizes Gemini's snake_case tool names (`run_shell_command`, `read_file`, `read_many_files`, `write_file`, `replace`, `glob`, `grep_search`, `list_directory`, `web_fetch`, `google_web_search`, `write_todos`, `save_memory`, `ask_user`) to Claude PascalCase (`Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `LS`, `WebFetch`, `WebSearch`, `TodoWrite`, `Memory`, `AskUser`) via `GEMINI_TOOL_MAP` so existing builtin policies (block-sudo, block-rm-rf, sanitize-api-keys, …) fire unchanged on Gemini sessions. MCP tool names (`mcp_<server>_<tool>` pattern) and Skills tool names pass through unchanged. The policy evaluator emits Gemini's flat `{decision: "deny", reason}` deny shape (preferred per Gemini's "Golden Rule" exit-0 contract), `{hookSpecificOutput: {hookEventName, additionalContext}}` for context injection on BeforeAgent / AfterTool / SessionStart, and `{decision: "block", reason}` on AfterAgent for force-retry semantics matching Claude's exit-2-from-Stop "do this before stopping" pattern. Path-protection (`isAgentInternalPath` + `isAgentSettingsFile`) covers `~/.gemini/` and `.gemini/settings.json`. Frontend: `lib/cli-registry.ts` adds a `Gemini CLI` entry with a sky-blue badge; `lib/projects.ts` merges Gemini projects into `/projects`; `app/project/[name]` and `/session/[id]` extend the external-CLI fallback chain. Also ships this repo's own `.gemini/settings.json` so contributors using `gemini` get hooks active automatically — uses `$GEMINI_PROJECT_DIR` for resolver stability (Gemini also sets `$CLAUDE_PROJECT_DIR` as a back-compat alias). Verified against gemini-cli v0.40.1 (#277).
 - Add OpenCode (sst/opencode) integration (beta) across hooks, activity dashboard, session viewer, and `/projects` listing. `--cli opencode` writes a generated plugin shim at `.opencode/plugins/failproofai.mjs` plus a registration entry in `opencode.json`'s `plugin: []` array; SQLite-backed dashboard adapters read OpenCode's session store via `opencode db --format json`. Verified against opencode v1.14.33 (#270).
 - Add Pi (`@mariozechner/pi-coding-agent`) integration (beta) across hooks, activity dashboard, session viewer, and `/projects` listing. `--cli pi` writes a `packages` entry into `.pi/settings.json` pointing at failproofai's bundled `pi-extension/`. Subscribes to all 7 Pi events (`tool_call`/`user_bash`/`input`/`session_start`/`tool_result`/`agent_end`/`session_shutdown`); the latter three are observation-only on Pi (no veto capability) but still activate the 5 PostToolUse and 5 `require-*-before-stop` builtins for visibility. Verified against pi-coding-agent v0.72.1 (#270).
 - Add GitHub Copilot CLI integration (beta) across hooks, activity dashboard, session fallback, and `/projects` listing. Also ships this repo's own `.github/hooks/failproofai.json` so contributors developing failproofai with the GitHub Copilot CLI get hooks active automatically, mirroring the existing `.claude/settings.json` and `.codex/hooks.json` (#236)
@@ -11,6 +11,7 @@
 - Project page (`/project/[name]`): list Copilot and Cursor sessions alongside Claude + Codex, mirroring the existing merge logic on the projects index. Previously the project detail view only enumerated Claude + Codex transcripts (#245).
 
 ### Fixes
+- Gemini integration (CodeRabbit follow-up): `lib/gemini-projects.ts` now uses `encodeFolderName(cwd)` for `ProjectFolder.name` so cross-CLI merge in `mergeProjectFolders` unions on the same key and Gemini-only project links resolve through `getGeminiSessionsByEncodedName`. `policy-evaluator.ts` preserves the raw CLI `--hook` arg via a new `SessionMetadata.rawHookEventName` field captured in `handler.ts` before canonicalization, so Gemini's `hookSpecificOutput.hookEventName` round-trips correctly even when stdin omits `hook_event_name`; deny-message construction now branches on event type so non-tool events (UserPromptSubmit / SessionStart / SessionEnd / Stop) emit "Blocked prompt|session start|…" instead of the misleading "Blocked unknown tool". `lib/gemini-sessions.ts` loosens `SESSION_FILE_RE` to accept any timestamp shape (Gemini docs include seconds; the load-bearing safety check is the first-line `sessionId` validation) and replaces the whole-file `readFileSync` in `findGeminiTranscript` with a bounded 4 KB `readFirstLineSync` helper so large transcripts no longer blow memory just to inspect the metadata header. `__tests__/lib/projects.test.ts` adds three Gemini aggregation tests (Gemini-only inclusion, cross-CLI merge by encoded slug, reject-fallback) mirroring the existing Pi / Cursor / OpenCode patterns (#277).
 - `block-read-outside-cwd`: deny message now says "Reading agent settings file blocked" instead of "Reading Claude settings file blocked" — the policy has covered all 6 CLIs' settings files since #270 / #245 / #220 but the deny string was stale (#270).
 - `require-ci-green-before-stop`: stop reporting historical CI failures as still-failing after a fix commit lands. The policy now filters `gh run list` results to runs whose `headSha` matches the current local HEAD, and deduplicates by workflow name so GitHub's "Re-run all jobs" doesn't resurface old failed run records. Also bumps the gh-run-list `--limit` from 5 to 20 to avoid truncating the latest run on busy branches with many workflows or recent pushes. Third-party checks (CodeRabbit, SonarCloud, …) and commit statuses already query by SHA and are unchanged. Resolves a wedge where a green PR could not satisfy the Stop policy because an earlier failed run on the same branch was still in the top-5 window. (#266)
 - `failproofai policies --uninstall` interactive CLI selector now says "Remove Hooks" / "Choose where to remove from:" instead of "Install Hooks" / "Choose where to install:" (#236)
@@ -19,7 +20,7 @@
 - Auto-translated MDX: stop the recurring `mintlify validate` parse error in `docs/de/dashboard.mdx` (`<Tab title="Tab „Richtlinien"">`) by adding a `sanitizeJsxAttributes` post-processor to the translation pipeline that strips stray ASCII `"` left after typographic-quote pairs (and any unmatched opening typographic quote) in JSX attribute values, and by tightening the translator system prompt to forbid ASCII `"` inside attribute values. Same regression PR #229 fixed by hand — now it can't recur. Includes the immediate file fix on `docs/de/dashboard.mdx`. (#247)
 
 ### Docs
-- README: add Gemini CLI to the supported-CLIs intro line and visual list, with light/dark logo variants (`assets/logos/gemini-light.svg` + `gemini-dark.svg`). Restructure the logo block into two centred `<p>` rows (Claude/Codex/Copilot/Cursor on the first, OpenCode/Pi/Gemini on the second) plus a separate "+ more coming soon" line so the seventh logo doesn't crowd the layout. Update the beta callout to include Gemini CLI alongside Copilot, Cursor, OpenCode, and Pi.
+- README: add Gemini CLI to the supported-CLIs intro line and visual list, with light/dark logo variants (`assets/logos/gemini-light.svg` + `gemini-dark.svg`). Restructure the logo block into two centred `<p>` rows (Claude/Codex/Copilot/Cursor on the first, OpenCode/Pi/Gemini on the second) plus a separate "+ more coming soon" line so the seventh logo doesn't crowd the layout. Update the beta callout to include Gemini CLI alongside Copilot, Cursor, OpenCode, and Pi (#277).
 - README: add Pi to the supported-CLIs intro line and visual list, with light/dark logo variants (`assets/logos/pi-light.svg` + `pi-dark.svg`); update beta callout to include Pi alongside Copilot and Cursor (#264).
 - README: add Cursor Agent to the supported-CLIs intro line and visual list, with light/dark logo variants (`assets/logos/cursor-light.svg` + `cursor-dark.svg`). Note that GitHub Copilot CLI testing is ongoing in the beta callout (#245).
 
diff --git a/__tests__/hooks/policy-evaluator.test.ts b/__tests__/hooks/policy-evaluator.test.ts
index ea10bf6b..22b338d5 100644
--- a/__tests__/hooks/policy-evaluator.test.ts
+++ b/__tests__/hooks/policy-evaluator.test.ts
@@ -891,5 +891,77 @@ describe("hooks/policy-evaluator", () => {
       expect(result.exitCode).toBe(0);
       expect(result.stdout).toBe("");
     });
+
+    it("instruct falls back to session.rawHookEventName when stdin omits hook_event_name", async () => {
+      registerPolicy("advisor", "desc", () => ({ decision: "instruct", reason: "consider X" }), {
+        events: ["PreToolUse"],
+      });
+      const result = await evaluatePolicies(
+        "PreToolUse",
+        { tool_name: "Bash" },
+        // session.hookEventName intentionally undefined; rawHookEventName carries
+        // the raw CLI --hook arg as captured by handler.ts.
+        { sessionId: "g", cwd: "/tmp", cli: "gemini", rawHookEventName: "BeforeTool" },
+      );
+      const parsed = JSON.parse(result.stdout);
+      // Must use the raw Gemini event name, NOT the canonicalized "PreToolUse".
+      expect(parsed.hookSpecificOutput.hookEventName).toBe("BeforeTool");
+    });
+
+    it("allow-with-context also falls back to session.rawHookEventName", async () => {
+      registerPolicy("info", "desc", () => ({ decision: "allow", reason: "fyi" }), {
+        events: ["UserPromptSubmit"],
+      });
+      const result = await evaluatePolicies(
+        "UserPromptSubmit",
+        { prompt: "x" },
+        { sessionId: "g", cwd: "/tmp", cli: "gemini", rawHookEventName: "BeforeAgent" },
+      );
+      const parsed = JSON.parse(result.stdout);
+      expect(parsed.hookSpecificOutput.hookEventName).toBe("BeforeAgent");
+    });
+
+    it("session.hookEventName from stdin still wins over rawHookEventName when both are set", async () => {
+      registerPolicy("advisor", "desc", () => ({ decision: "instruct", reason: "x" }), {
+        events: ["PreToolUse"],
+      });
+      const result = await evaluatePolicies(
+        "PreToolUse",
+        { tool_name: "Bash" },
+        { sessionId: "g", cwd: "/tmp", cli: "gemini", hookEventName: "BeforeTool", rawHookEventName: "RawShouldLose" },
+      );
+      const parsed = JSON.parse(result.stdout);
+      expect(parsed.hookSpecificOutput.hookEventName).toBe("BeforeTool");
+    });
+
+    it("UserPromptSubmit deny on Gemini emits event-appropriate text (NOT 'Blocked unknown tool')", async () => {
+      registerPolicy("prompt-block", "desc", () => ({ decision: "deny", reason: "bad prompt" }), {
+        events: ["UserPromptSubmit"],
+      });
+      const result = await evaluatePolicies(
+        "UserPromptSubmit",
+        { prompt: "<bad>" },
+        geminiSession("BeforeAgent"),
+      );
+      const parsed = JSON.parse(result.stdout);
+      // Without ctx.toolName, the deny message used to say "Blocked unknown tool";
+      // now we branch on event type.
+      expect(parsed.reason).toMatch(/Blocked prompt/);
+      expect(parsed.reason).not.toMatch(/Blocked unknown tool/);
+    });
+
+    it("SessionStart deny emits 'Blocked session start' label, not 'unknown tool'", async () => {
+      registerPolicy("greet-block", "desc", () => ({ decision: "deny", reason: "no greeting" }), {
+        events: ["SessionStart"],
+      });
+      const result = await evaluatePolicies(
+        "SessionStart",
+        {},
+        geminiSession("SessionStart"),
+      );
+      const parsed = JSON.parse(result.stdout);
+      expect(parsed.reason).toMatch(/Blocked session start/);
+      expect(parsed.reason).not.toMatch(/Blocked unknown tool/);
+    });
   });
 });
diff --git a/__tests__/lib/projects.test.ts b/__tests__/lib/projects.test.ts
index 07b14b57..0d012366 100644
--- a/__tests__/lib/projects.test.ts
+++ b/__tests__/lib/projects.test.ts
@@ -526,6 +526,65 @@ describe("getProjectFolders", () => {
     expect(result[0].cli).toEqual(["claude"]);
   });
 
+  it("includes Gemini-only projects (no matching Claude/Codex/Copilot/Cursor/OpenCode/Pi folder)", async () => {
+    mockStat.mockResolvedValueOnce({ isDirectory: () => true } as any);
+    mockReaddir.mockResolvedValueOnce([] as any);
+    mockGetGeminiProjects.mockResolvedValueOnce([
+      {
+        name: "-home-u-gemini-only",
+        path: "/home/u/gemini-only",
+        isDirectory: true,
+        lastModified: new Date("2026-08-15T00:00:00Z"),
+        lastModifiedFormatted: "2026-08-15T00:00:00.000Z",
+        cli: ["gemini"],
+      } satisfies ProjectFolder,
+    ]);
+
+    const result = await getProjectFolders();
+    expect(result).toHaveLength(1);
+    expect(result[0].cli).toEqual(["gemini"]);
+    expect(result[0].path).toBe("/home/u/gemini-only");
+  });
+
+  it("merges a Gemini project with the same encoded name into one row with both badges", async () => {
+    mockStat.mockResolvedValueOnce({ isDirectory: () => true } as any);
+    mockReaddir.mockResolvedValueOnce([
+      { name: "-home-u-shared", isDirectory: () => true, isFile: () => false } as any,
+    ] as any);
+    mockStat.mockResolvedValueOnce({ mtime: new Date("2026-04-01T00:00:00Z") } as any);
+    mockGetGeminiProjects.mockResolvedValueOnce([
+      {
+        name: "-home-u-shared",
+        path: "/home/u/shared",
+        isDirectory: true,
+        lastModified: new Date("2026-09-01T00:00:00Z"),
+        lastModifiedFormatted: "2026-09-01T00:00:00.000Z",
+        cli: ["gemini"],
+      } satisfies ProjectFolder,
+    ]);
+
+    const result = await getProjectFolders();
+    expect(result).toHaveLength(1);
+    // Claude registered first → cli order is ["claude", "gemini"]; lastModified
+    // takes the newer Gemini date (Sept > April) so the row sorts to the top.
+    expect(result[0].cli).toEqual(["claude", "gemini"]);
+    expect(result[0].lastModified.toISOString()).toBe("2026-09-01T00:00:00.000Z");
+  });
+
+  it("falls back gracefully when getGeminiProjects rejects", async () => {
+    mockStat.mockResolvedValueOnce({ isDirectory: () => true } as any);
+    mockReaddir.mockResolvedValueOnce([
+      { name: "-home-u-claude", isDirectory: () => true, isFile: () => false } as any,
+    ] as any);
+    mockStat.mockResolvedValueOnce({ mtime: new Date("2026-04-01T00:00:00Z") } as any);
+    mockGetGeminiProjects.mockRejectedValueOnce(new Error("scan failed"));
+
+    const result = await getProjectFolders();
+    // Claude row still surfaces even though Gemini scan blew up.
+    expect(result).toHaveLength(1);
+    expect(result[0].cli).toEqual(["claude"]);
+  });
+
   it("falls back gracefully when getCursorProjects rejects", async () => {
     mockStat.mockResolvedValueOnce({ isDirectory: () => true } as any);
     mockReaddir.mockResolvedValueOnce([
diff --git a/lib/gemini-projects.ts b/lib/gemini-projects.ts
index f04bc515..a3acdb55 100644
--- a/lib/gemini-projects.ts
+++ b/lib/gemini-projects.ts
@@ -110,19 +110,22 @@ async function scanGeminiSessions(): Promise<GeminiSessionMeta[]> {
   return out;
 }
 
-/** Returns one ProjectFolder per unique cwd that has at least one session file. */
+/** Returns one ProjectFolder per unique cwd that has at least one session file.
+ *  `name` is the encoded full-cwd slug (`encodeFolderName(cwd)`), matching the
+ *  routing scheme used by the dashboard's project URL — `mergeProjectFolders`
+ *  unions by `name`, and `getGeminiSessionsByEncodedName` looks up by the same
+ *  slug, so every cross-CLI merge and Gemini-only project link round-trips. */
 export async function getGeminiProjects(): Promise<ProjectFolder[]> {
   const sessions = await scanGeminiSessions();
-  const byCwd = new Map<string, { mtime: Date; basename: string }>();
+  const byCwd = new Map<string, { mtime: Date }>();
   for (const s of sessions) {
-    const basename = s.cwd.split("/").filter(Boolean).pop() ?? s.cwd;
     const existing = byCwd.get(s.cwd);
     if (!existing || s.fileMtime.getTime() > existing.mtime.getTime()) {
-      byCwd.set(s.cwd, { mtime: s.fileMtime, basename });
+      byCwd.set(s.cwd, { mtime: s.fileMtime });
     }
   }
-  const folders: ProjectFolder[] = [...byCwd.entries()].map(([cwd, { mtime, basename }]) => ({
-    name: basename,
+  const folders: ProjectFolder[] = [...byCwd.entries()].map(([cwd, { mtime }]) => ({
+    name: encodeFolderName(cwd),
     path: cwd,
     isDirectory: true,
     lastModified: mtime,
diff --git a/lib/gemini-sessions.ts b/lib/gemini-sessions.ts
index a5b28acb..601aa034 100644
--- a/lib/gemini-sessions.ts
+++ b/lib/gemini-sessions.ts
@@ -19,7 +19,7 @@
  * "system" entries; malformed lines are skipped without aborting; and the
  * loader fall-opens (returns null) on any I/O or parse failure.
  */
-import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
+import { closeSync, openSync, readFileSync, readSync, readdirSync, existsSync, statSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { join, resolve, sep } from "node:path";
 import { homedir } from "node:os";
@@ -38,7 +38,12 @@ import {
 // ── Paths ──
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const SESSION_FILE_RE = /^session-(\d{4}-\d{2}-\d{2}T\d{2}-\d{2})-([0-9a-f]{8})\.jsonl$/i;
+/** Matches `session-<timestamp-of-arbitrary-shape>-<8-hex-uuid-prefix>.jsonl`.
+ *  Empirically gemini-cli v0.40.1 emits minute-precision (`YYYY-MM-DDTHH-mm`),
+ *  but the documented format includes seconds (`YYYY-MM-DDTHH-mm:ss`) and may
+ *  evolve further. The first-line `sessionId` validation in findGeminiTranscript
+ *  is the load-bearing safety check, so we accept any timestamp shape. */
+const SESSION_FILE_RE = /^session-(.+)-([0-9a-f]{8})\.jsonl$/i;
 
 /** Root directory for Gemini session state, honoring GEMINI_SESSIONS_DIR. */
 export function getGeminiSessionStateRoot(): string {
@@ -51,6 +56,38 @@ function isSafeSessionId(sessionId: string): boolean {
   return UUID_RE.test(sessionId);
 }
 
+/**
+ * Read up to the first newline from `path` without loading the whole file.
+ * Used by `findGeminiTranscript` to inspect the JSONL metadata header on
+ * candidate matches; the typical header is well under 1KB and we cap at 4KB
+ * for safety so a degenerate single-line file can't blow memory.
+ *
+ * Returns the first line as a UTF-8 string, or null on read failure / empty
+ * file. If the first 4KB contain no newline, returns whatever was read so the
+ * JSON.parse caller can still attempt — JSON.parse will fail for a truncated
+ * object, which findGeminiTranscript treats as a malformed-header miss.
+ */
+function readFirstLineSync(path: string): string | null {
+  let fd: number;
+  try {
+    fd = openSync(path, "r");
+  } catch {
+    return null;
+  }
+  try {
+    const buf = Buffer.alloc(4096);
+    const bytesRead = readSync(fd, buf, 0, buf.length, 0);
+    if (bytesRead === 0) return null;
+    const text = buf.subarray(0, bytesRead).toString("utf-8");
+    const nl = text.indexOf("\n");
+    return nl >= 0 ? text.slice(0, nl) : text;
+  } catch {
+    return null;
+  } finally {
+    try { closeSync(fd); } catch { /* best-effort */ }
+  }
+}
+
 /**
  * Find the JSONL transcript for `sessionId`. Walks every per-project subdir's
  * `chats/` directory, matches the 8-hex prefix, and verifies the first record's
@@ -88,9 +125,12 @@ export function findGeminiTranscript(sessionId: string): string | null {
       if (!candidate.startsWith(`${chatsDir}${sep}`)) continue;
       if (!existsSync(candidate)) continue;
       // Confirm the full sessionId — the 8-hex prefix isn't unique on its own.
+      // Read only the first ~4KB so large transcripts don't bloat memory; the
+      // metadata header sits on line 1 well within that bound. The full file
+      // is re-read in getGeminiSessionLog() once we've matched.
+      const firstLine = readFirstLineSync(candidate);
+      if (!firstLine) continue;
       try {
-        const head = readFileSync(candidate, "utf-8");
-        const firstLine = head.indexOf("\n") >= 0 ? head.slice(0, head.indexOf("\n")) : head;
         const meta = JSON.parse(firstLine) as { sessionId?: unknown };
         if (typeof meta.sessionId === "string" && meta.sessionId.toLowerCase() === sessionId.toLowerCase()) {
           return candidate;
diff --git a/src/hooks/handler.ts b/src/hooks/handler.ts
index f7c27aed..0ac09b5b 100644
--- a/src/hooks/handler.ts
+++ b/src/hooks/handler.ts
@@ -144,6 +144,11 @@ export async function handleHookEvent(
     cwd: parsed.cwd as string | undefined,
     permissionMode: resolvePermissionMode(cli, parsed, sessionId),
     hookEventName: parsed.hook_event_name as string | undefined,
+    // Preserve the raw CLI-side event name (eventType arg) before
+    // canonicalization. Response shapes that round-trip the agent-emitted
+    // event name (e.g. Gemini's `hookSpecificOutput.hookEventName`) prefer
+    // this over the canonicalized form when stdin omits hook_event_name.
+    rawHookEventName: eventType,
     cli,
   };
 
diff --git a/src/hooks/policy-evaluator.ts b/src/hooks/policy-evaluator.ts
index 45434ceb..602f829c 100644
--- a/src/hooks/policy-evaluator.ts
+++ b/src/hooks/policy-evaluator.ts
@@ -118,7 +118,24 @@ export async function evaluatePolicies(
       );
       hookLogInfo(`deny by "${policy.name}": ${reason}`);
 
-      const displayTool = ctx.toolName ?? "unknown tool";
+      // Pick a noun for the deny message that fits the event type. Tool events
+      // get the tool name; non-tool events (UserPromptSubmit, SessionStart,
+      // SessionEnd, Stop, …) use an event-appropriate label so we don't emit
+      // the misleading "Blocked unknown tool by failproofai because: ...".
+      let displayTool: string;
+      if (ctx.toolName) {
+        displayTool = ctx.toolName;
+      } else if (eventType === "UserPromptSubmit") {
+        displayTool = "prompt";
+      } else if (eventType === "SessionStart") {
+        displayTool = "session start";
+      } else if (eventType === "SessionEnd") {
+        displayTool = "session end";
+      } else if (eventType === "Stop") {
+        displayTool = "stop";
+      } else {
+        displayTool = "operation";
+      }
       const blockedMessage = `Blocked ${displayTool} by failproofai because: ${reason}, as per the policy configured by the user`;
 
       // Cursor's hook protocol expects a flat `{permission, user_message,
@@ -377,7 +394,13 @@ export async function evaluatePolicies(
         eventType === "PostToolUse" ||
         eventType === "SessionStart";
       if (supportsContext) {
-        const hookEventName = session?.hookEventName ?? eventType;
+        // Round-trip the agent-emitted event name so Gemini sees `BeforeTool`,
+        // `BeforeAgent`, etc. (NOT the canonical Claude form). Prefer the
+        // stdin payload's `hook_event_name` when present; fall back to the raw
+        // CLI `--hook` arg captured by handler.ts; only use the canonical
+        // event as a last resort (would never round-trip correctly, but better
+        // than emitting nothing).
+        const hookEventName = session?.hookEventName ?? session?.rawHookEventName ?? eventType;
         const response = {
           hookSpecificOutput: {
             hookEventName,
@@ -502,7 +525,8 @@ export async function evaluatePolicies(
         .map((e) => `[failproofai] ${e.policyName}: ${e.reason}`)
         .join("\n");
       if (supportsContext) {
-        const hookEventName = session?.hookEventName ?? eventType;
+        // Same fallback chain as the instruct path above — see comment there.
+        const hookEventName = session?.hookEventName ?? session?.rawHookEventName ?? eventType;
         const response = {
           hookSpecificOutput: {
             hookEventName,
diff --git a/src/hooks/types.ts b/src/hooks/types.ts
index 518f147f..ed6cfe63 100644
--- a/src/hooks/types.ts
+++ b/src/hooks/types.ts
@@ -377,7 +377,15 @@ export interface SessionMetadata {
   transcriptPath?: string;
   cwd?: string;
   permissionMode?: string;
+  /** Read from the stdin payload's `hook_event_name` field. Carries the raw
+   *  agent-emitted event name (e.g. Gemini's `BeforeTool`, Cursor's
+   *  `preToolUse`, Pi's `tool_call`). May be undefined when stdin omits it. */
   hookEventName?: string;
+  /** The raw event name passed on the CLI's `--hook` flag, BEFORE any
+   *  per-CLI canonicalization to PascalCase (e.g. `BeforeTool` for Gemini,
+   *  `preToolUse` for Cursor). Use this for round-tripping the agent-side
+   *  event name in response shapes when stdin doesn't include `hook_event_name`. */
+  rawHookEventName?: string;
   /** Which agent CLI fired this hook (claude | codex | copilot | cursor | opencode | pi | gemini). Set by handler.ts from --cli. */
   cli?: IntegrationType;
 }