feat(hooks): Hooks Commands Panel, Enable/Disable, and Migrate (#14225)

packages/cli/src/commands/hooks.tsx

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { CommandModule } from 'yargs';
+import { migrateCommand } from './hooks/migrate.js';
+import { initializeOutputListenersAndFlush } from '../gemini.js';
+
+export const hooksCommand: CommandModule = {
+  command: 'hooks <command>',
+  aliases: ['hook'],
+  describe: 'Manage Gemini CLI hooks.',
+  builder: (yargs) =>
+    yargs
+      .middleware(() => initializeOutputListenersAndFlush())
+      .command(migrateCommand)
+      .demandCommand(1, 'You need at least one command before continuing.')
+      .version(false),
+  handler: () => {
+    // This handler is not called when a subcommand is provided.
+    // Yargs will show the help menu.
+  },
+};

packages/cli/src/commands/hooks/migrate.test.ts

@@ -0,0 +1,518 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  afterEach,
+  type Mock,
+  type MockInstance,
+} from 'vitest';
+import * as fs from 'node:fs';
+import { loadSettings, SettingScope } from '../../config/settings.js';
+import { debugLogger } from '@google/gemini-cli-core';
+import { handleMigrateFromClaude } from './migrate.js';
+
+vi.mock('node:fs');
+vi.mock('../utils.js', () => ({
+  exitCli: vi.fn(),
+}));
+
+vi.mock('../../config/settings.js', async () => {
+  const actual = await vi.importActual('../../config/settings.js');
+  return {
+    ...actual,
+    loadSettings: vi.fn(),
+  };
+});
+
+const mockedLoadSettings = loadSettings as Mock;
+const mockedFs = vi.mocked(fs);
+
+describe('migrate command', () => {
+  let mockSetValue: Mock;
+  let debugLoggerLogSpy: MockInstance;
+  let debugLoggerErrorSpy: MockInstance;
+  let originalCwd: () => string;
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+
+    mockSetValue = vi.fn();
+    debugLoggerLogSpy = vi
+      .spyOn(debugLogger, 'log')
+      .mockImplementation(() => {});
+    debugLoggerErrorSpy = vi
+      .spyOn(debugLogger, 'error')
+      .mockImplementation(() => {});
+
+    // Mock process.cwd()
+    originalCwd = process.cwd;
+    process.cwd = vi.fn(() => '/test/project');
+
+    mockedLoadSettings.mockReturnValue({
+      merged: {
+        hooks: {},
+      },
+      setValue: mockSetValue,
+      workspace: { path: '/test/project/.gemini' },
+    });
+  });
+
+  afterEach(() => {
+    process.cwd = originalCwd;
+    vi.restoreAllMocks();
+  });
+
+  it('should log error when no Claude settings files exist', async () => {
+    mockedFs.existsSync.mockReturnValue(false);
+
+    await handleMigrateFromClaude();
+
+    expect(debugLoggerErrorSpy).toHaveBeenCalledWith(
+      'No Claude Code settings found in .claude directory. Expected settings.json or settings.local.json',
+    );
+    expect(mockSetValue).not.toHaveBeenCalled();
+  });
+
+  it('should migrate hooks from settings.json when it exists', async () => {
+    const claudeSettings = {
+      hooks: {
+        PreToolUse: [
+          {
+            matcher: 'Edit',
+            hooks: [
+              {
+                type: 'command',
+                command: 'echo "Before Edit"',
+                timeout: 30,
+              },
+            ],
+          },
+        ],
+      },
+    };
+
+    mockedFs.existsSync.mockImplementation((path) =>
+      path.toString().endsWith('settings.json'),
+    );
+
+    mockedFs.readFileSync.mockReturnValue(JSON.stringify(claudeSettings));
+
+    await handleMigrateFromClaude();
+
+    expect(mockSetValue).toHaveBeenCalledWith(
+      SettingScope.Workspace,
+      'hooks',
+      expect.objectContaining({
+        BeforeTool: expect.arrayContaining([
+          expect.objectContaining({
+            matcher: 'replace',
+            hooks: expect.arrayContaining([
+              expect.objectContaining({
+                command: 'echo "Before Edit"',
+                type: 'command',
+                timeout: 30,
+              }),
+            ]),
+          }),
+        ]),
+      }),
+    );
+
+    expect(debugLoggerLogSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Found Claude Code settings'),
+    );
+    expect(debugLoggerLogSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Migrating 1 hook event'),
+    );
+    expect(debugLoggerLogSpy).toHaveBeenCalledWith(
+      '✓ Hooks successfully migrated to .gemini/settings.json',
+    );
+  });
+
+  it('should prefer settings.local.json over settings.json', async () => {
+    const localSettings = {
+      hooks: {
+        SessionStart: [
+          {
+            hooks: [
+              {
+                type: 'command',
+                command: 'echo "Local session start"',
+              },
+            ],
+          },
+        ],
+      },
+    };
+
+    mockedFs.existsSync.mockReturnValue(true);
+    mockedFs.readFileSync.mockReturnValue(JSON.stringify(localSettings));
+
+    await handleMigrateFromClaude();
+
+    expect(mockedFs.readFileSync).toHaveBeenCalledWith(
+      expect.stringContaining('settings.local.json'),
+      'utf-8',
+    );
+    expect(mockSetValue).toHaveBeenCalledWith(
+      SettingScope.Workspace,
+      'hooks',
+      expect.objectContaining({
+        SessionStart: expect.any(Array),
+      }),
+    );
+  });
+
+  it('should migrate all supported event types', async () => {
+    const claudeSettings = {
+      hooks: {
+        PreToolUse: [{ hooks: [{ type: 'command', command: 'echo 1' }] }],
+        PostToolUse: [{ hooks: [{ type: 'command', command: 'echo 2' }] }],
+        UserPromptSubmit: [{ hooks: [{ type: 'command', command: 'echo 3' }] }],
+        Stop: [{ hooks: [{ type: 'command', command: 'echo 4' }] }],
+        SubAgentStop: [{ hooks: [{ type: 'command', command: 'echo 5' }] }],
+        SessionStart: [{ hooks: [{ type: 'command', command: 'echo 6' }] }],
+        SessionEnd: [{ hooks: [{ type: 'command', command: 'echo 7' }] }],
+        PreCompact: [{ hooks: [{ type: 'command', command: 'echo 8' }] }],
+        Notification: [{ hooks: [{ type: 'command', command: 'echo 9' }] }],
+      },
+    };
+
+    mockedFs.existsSync.mockReturnValue(true);
+    mockedFs.readFileSync.mockReturnValue(JSON.stringify(claudeSettings));
+
+    await handleMigrateFromClaude();
+
+    const migratedHooks = mockSetValue.mock.calls[0][2];
+
+    expect(migratedHooks).toHaveProperty('BeforeTool');
+    expect(migratedHooks).toHaveProperty('AfterTool');
+    expect(migratedHooks).toHaveProperty('BeforeAgent');
+    expect(migratedHooks).toHaveProperty('AfterAgent');
+    expect(migratedHooks).toHaveProperty('SessionStart');
+    expect(migratedHooks).toHaveProperty('SessionEnd');
+    expect(migratedHooks).toHaveProperty('PreCompress');
+    expect(migratedHooks).toHaveProperty('Notification');
+  });
+
+  it('should transform tool names in matchers', async () => {
+    const claudeSettings = {
+      hooks: {
+        PreToolUse: [
+          {
+            matcher: 'Edit|Bash|Read|Write|Glob|Grep',
+            hooks: [{ type: 'command', command: 'echo "test"' }],
+          },
+        ],
+      },
+    };
+
+    mockedFs.existsSync.mockReturnValue(true);
+    mockedFs.readFileSync.mockReturnValue(JSON.stringify(claudeSettings));
+
+    await handleMigrateFromClaude();
+
+    const migratedHooks = mockSetValue.mock.calls[0][2];
+    expect(migratedHooks.BeforeTool[0].matcher).toBe(
+      'replace|run_shell_command|read_file|write_file|glob|grep',
+    );
+  });
+
+  it('should replace $CLAUDE_PROJECT_DIR with $GEMINI_PROJECT_DIR', async () => {
+    const claudeSettings = {
+      hooks: {
+        PreToolUse: [
+          {
+            hooks: [
+              {
+                type: 'command',
+                command: 'cd $CLAUDE_PROJECT_DIR && ls',
+              },
+            ],
+          },
+        ],
+      },
+    };
+
+    mockedFs.existsSync.mockReturnValue(true);
+    mockedFs.readFileSync.mockReturnValue(JSON.stringify(claudeSettings));
+
+    await handleMigrateFromClaude();
+
+    const migratedHooks = mockSetValue.mock.calls[0][2];
+    expect(migratedHooks.BeforeTool[0].hooks[0].command).toBe(
+      'cd $GEMINI_PROJECT_DIR && ls',
+    );
+  });
+
+  it('should preserve sequential flag', async () => {
+    const claudeSettings = {
+      hooks: {
+        PreToolUse: [
+          {
+            sequential: true,
+            hooks: [{ type: 'command', command: 'echo "test"' }],
+          },
+        ],
+      },
+    };
+
+    mockedFs.existsSync.mockReturnValue(true);
+    mockedFs.readFileSync.mockReturnValue(JSON.stringify(claudeSettings));
+
+    await handleMigrateFromClaude();
+
+    const migratedHooks = mockSetValue.mock.calls[0][2];
+    expect(migratedHooks.BeforeTool[0].sequential).toBe(true);
+  });
+
+  it('should preserve timeout values', async () => {
+    const claudeSettings = {
+      hooks: {
+        PreToolUse: [
+          {
+            hooks: [
+              {
+                type: 'command',
+                command: 'echo "test"',
+                timeout: 60,
+              },
+            ],
+          },
+        ],
+      },
+    };
+
+    mockedFs.existsSync.mockReturnValue(true);
+    mockedFs.readFileSync.mockReturnValue(JSON.stringify(claudeSettings));
+
+    await handleMigrateFromClaude();
+
+    const migratedHooks = mockSetValue.mock.calls[0][2];
+    expect(migratedHooks.BeforeTool[0].hooks[0].timeout).toBe(60);
+  });
+
+  it('should merge with existing Gemini hooks', async () => {
+    const claudeSettings = {
+      hooks: {
+        PreToolUse: [
+          {
+            hooks: [{ type: 'command', command: 'echo "claude"' }],
+          },
+        ],
+      },
+    };
+
+    mockedLoadSettings.mockReturnValue({
+      merged: {
+        hooks: {
+          AfterTool: [
+            {
+              hooks: [{ type: 'command', command: 'echo "existing"' }],
+            },
+          ],
+        },
+      },
+      setValue: mockSetValue,
+      workspace: { path: '/test/project/.gemini' },
+    });
+
+    mockedFs.existsSync.mockReturnValue(true);
+    mockedFs.readFileSync.mockReturnValue(JSON.stringify(claudeSettings));
+
+    await handleMigrateFromClaude();
+
+    const migratedHooks = mockSetValue.mock.calls[0][2];
+    expect(migratedHooks).toHaveProperty('BeforeTool');
+    expect(migratedHooks).toHaveProperty('AfterTool');
+    expect(migratedHooks.AfterTool[0].hooks[0].command).toBe('echo "existing"');
+    expect(migratedHooks.BeforeTool[0].hooks[0].command).toBe('echo "claude"');
+  });
+
+  it('should handle JSON with comments', async () => {
+    const claudeSettingsWithComments = `{
+      // This is a comment
+      "hooks": {
+        /* Block comment */
+        "PreToolUse": [
+          {
+            "hooks": [
+              {
+                "type": "command",
+                "command": "echo test" // Inline comment
+              }
+            ]
+          }
+        ]
+      }
+    }`;
+
+    mockedFs.existsSync.mockReturnValue(true);
+    mockedFs.readFileSync.mockReturnValue(claudeSettingsWithComments);
+
+    await handleMigrateFromClaude();
+
+    expect(mockSetValue).toHaveBeenCalledWith(
+      SettingScope.Workspace,
+      'hooks',
+      expect.objectContaining({
+        BeforeTool: expect.any(Array),
+      }),
+    );
+  });
+
+  it('should handle malformed JSON gracefully', async () => {
+    mockedFs.existsSync.mockReturnValue(true);
+    mockedFs.readFileSync.mockReturnValue('{ invalid json }');
+
+    await handleMigrateFromClaude();
+
+    expect(debugLoggerErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Error reading'),
+    );
+    expect(mockSetValue).not.toHaveBeenCalled();
+  });
+
+  it('should log info when no hooks are found in Claude settings', async () => {
+    const claudeSettings = {
+      someOtherSetting: 'value',
+    };
+
+    mockedFs.existsSync.mockReturnValue(true);
+    mockedFs.readFileSync.mockReturnValue(JSON.stringify(claudeSettings));
+
+    await handleMigrateFromClaude();
+
+    expect(debugLoggerLogSpy).toHaveBeenCalledWith(
+      'No hooks found in Claude Code settings to migrate.',
+    );
+    expect(mockSetValue).not.toHaveBeenCalled();
+  });
+
+  it('should handle setValue errors gracefully', async () => {
+    const claudeSettings = {
+      hooks: {
+        PreToolUse: [
+          {
+            hooks: [{ type: 'command', command: 'echo "test"' }],
+          },
+        ],
+      },
+    };
+
+    mockedFs.existsSync.mockReturnValue(true);
+    mockedFs.readFileSync.mockReturnValue(JSON.stringify(claudeSettings));
+    mockSetValue.mockImplementation(() => {
+      throw new Error('Failed to save');
+    });
+
+    await handleMigrateFromClaude();
+
+    expect(debugLoggerErrorSpy).toHaveBeenCalledWith(
+      'Error saving migrated hooks: Failed to save',
+    );
+  });
+
+  it('should handle hooks with matcher but no command', async () => {
+    const claudeSettings = {
+      hooks: {
+        PreToolUse: [
+          {
+            matcher: 'Edit',
+            hooks: [
+              {
+                type: 'command',
+              },
+            ],
+          },
+        ],
+      },
+    };
+
+    mockedFs.existsSync.mockReturnValue(true);
+    mockedFs.readFileSync.mockReturnValue(JSON.stringify(claudeSettings));
+
+    await handleMigrateFromClaude();
+
+    const migratedHooks = mockSetValue.mock.calls[0][2];
+    expect(migratedHooks.BeforeTool[0].matcher).toBe('replace');
+    expect(migratedHooks.BeforeTool[0].hooks[0].type).toBe('command');
+  });
+
+  it('should handle empty hooks array', async () => {
+    const claudeSettings = {
+      hooks: {
+        PreToolUse: [
+          {
+            hooks: [],
+          },
+        ],
+      },
+    };
+
+    mockedFs.existsSync.mockReturnValue(true);
+    mockedFs.readFileSync.mockReturnValue(JSON.stringify(claudeSettings));
+
+    await handleMigrateFromClaude();
+
+    const migratedHooks = mockSetValue.mock.calls[0][2];
+    expect(migratedHooks.BeforeTool[0].hooks).toEqual([]);
+  });
+
+  it('should handle non-array event config gracefully', async () => {
+    const claudeSettings = {
+      hooks: {
+        PreToolUse: 'not an array',
+        PostToolUse: [
+          {
+            hooks: [{ type: 'command', command: 'echo "test"' }],
+          },
+        ],
+      },
+    };
+
+    mockedFs.existsSync.mockReturnValue(true);
+    mockedFs.readFileSync.mockReturnValue(JSON.stringify(claudeSettings));
+
+    await handleMigrateFromClaude();
+
+    const migratedHooks = mockSetValue.mock.calls[0][2];
+    expect(migratedHooks).not.toHaveProperty('BeforeTool');
+    expect(migratedHooks).toHaveProperty('AfterTool');
+  });
+
+  it('should display migration instructions after successful migration', async () => {
+    const claudeSettings = {
+      hooks: {
+        PreToolUse: [
+          {
+            hooks: [{ type: 'command', command: 'echo "test"' }],
+          },
+        ],
+      },
+    };
+
+    mockedFs.existsSync.mockReturnValue(true);
+    mockedFs.readFileSync.mockReturnValue(JSON.stringify(claudeSettings));
+
+    await handleMigrateFromClaude();
+
+    expect(debugLoggerLogSpy).toHaveBeenCalledWith(
+      '✓ Hooks successfully migrated to .gemini/settings.json',
+    );
+    expect(debugLoggerLogSpy).toHaveBeenCalledWith(
+      '\nMigration complete! Please review the migrated hooks in .gemini/settings.json',
+    );
+    expect(debugLoggerLogSpy).toHaveBeenCalledWith(
+      'Note: Set tools.enableHooks to true in your settings to enable the hook system.',
+    );
+  });
+});

packages/cli/src/commands/hooks/migrate.ts

@@ -0,0 +1,273 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { CommandModule } from 'yargs';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { debugLogger, getErrorMessage } from '@google/gemini-cli-core';
+import { loadSettings, SettingScope } from '../../config/settings.js';
+import { exitCli } from '../utils.js';
+import stripJsonComments from 'strip-json-comments';
+
+interface MigrateArgs {
+  fromClaude: boolean;
+}
+
+/**
+ * Mapping from Claude Code event names to Gemini event names
+ */
+const EVENT_MAPPING: Record<string, string> = {
+  PreToolUse: 'BeforeTool',
+  PostToolUse: 'AfterTool',
+  UserPromptSubmit: 'BeforeAgent',
+  Stop: 'AfterAgent',
+  SubAgentStop: 'AfterAgent', // Gemini doesn't have sub-agents, map to AfterAgent
+  SessionStart: 'SessionStart',
+  SessionEnd: 'SessionEnd',
+  PreCompact: 'PreCompress',
+  Notification: 'Notification',
+};
+
+/**
+ * Mapping from Claude Code tool names to Gemini tool names
+ */
+const TOOL_NAME_MAPPING: Record<string, string> = {
+  Edit: 'replace',
+  Bash: 'run_shell_command',
+  Read: 'read_file',
+  Write: 'write_file',
+  Glob: 'glob',
+  Grep: 'grep',
+  LS: 'ls',
+};
+
+/**
+ * Transform a matcher regex to update tool names from Claude to Gemini
+ */
+function transformMatcher(matcher: string | undefined): string | undefined {
+  if (!matcher) return matcher;
+
+  let transformed = matcher;
+  for (const [claudeName, geminiName] of Object.entries(TOOL_NAME_MAPPING)) {
+    // Replace exact matches and matches within regex alternations
+    transformed = transformed.replace(
+      new RegExp(`\\b${claudeName}\\b`, 'g'),
+      geminiName,
+    );
+  }
+
+  return transformed;
+}
+
+/**
+ * Migrate a Claude Code hook configuration to Gemini format
+ */
+function migrateClaudeHook(claudeHook: unknown): unknown {
+  if (!claudeHook || typeof claudeHook !== 'object') {
+    return claudeHook;
+  }
+
+  const hook = claudeHook as Record<string, unknown>;
+  const migrated: Record<string, unknown> = {};
+
+  // Map command field
+  if ('command' in hook) {
+    migrated['command'] = hook['command'];
+
+    // Replace CLAUDE_PROJECT_DIR with GEMINI_PROJECT_DIR in command
+    if (typeof migrated['command'] === 'string') {
+      migrated['command'] = migrated['command'].replace(
+        /\$CLAUDE_PROJECT_DIR/g,
+        '$GEMINI_PROJECT_DIR',
+      );
+    }
+  }
+
+  // Map type field
+  if ('type' in hook && hook['type'] === 'command') {
+    migrated['type'] = 'command';
+  }
+
+  // Map timeout field (Claude uses seconds, Gemini uses seconds)
+  if ('timeout' in hook && typeof hook['timeout'] === 'number') {
+    migrated['timeout'] = hook['timeout'];
+  }
+
+  return migrated;
+}
+
+/**
+ * Migrate Claude Code hooks configuration to Gemini format
+ */
+function migrateClaudeHooks(claudeConfig: unknown): Record<string, unknown> {
+  if (!claudeConfig || typeof claudeConfig !== 'object') {
+    return {};
+  }
+
+  const config = claudeConfig as Record<string, unknown>;
+  const geminiHooks: Record<string, unknown> = {};
+
+  // Check if there's a hooks section
+  const hooksSection = config['hooks'] as Record<string, unknown> | undefined;
+  if (!hooksSection || typeof hooksSection !== 'object') {
+    return {};
+  }
+
+  for (const [eventName, eventConfig] of Object.entries(hooksSection)) {
+    // Map event name
+    const geminiEventName = EVENT_MAPPING[eventName] || eventName;
+
+    if (!Array.isArray(eventConfig)) {
+      continue;
+    }
+
+    // Migrate each hook definition
+    const migratedDefinitions = eventConfig.map((def: unknown) => {
+      if (!def || typeof def !== 'object') {
+        return def;
+      }
+
+      const definition = def as Record<string, unknown>;
+      const migratedDef: Record<string, unknown> = {};
+
+      // Transform matcher
+      if (
+        'matcher' in definition &&
+        typeof definition['matcher'] === 'string'
+      ) {
+        migratedDef['matcher'] = transformMatcher(definition['matcher']);
+      }
+
+      // Copy sequential flag
+      if ('sequential' in definition) {
+        migratedDef['sequential'] = definition['sequential'];
+      }
+
+      // Migrate hooks array
+      if ('hooks' in definition && Array.isArray(definition['hooks'])) {
+        migratedDef['hooks'] = definition['hooks'].map(migrateClaudeHook);
+      }
+
+      return migratedDef;
+    });
+
+    geminiHooks[geminiEventName] = migratedDefinitions;
+  }
+
+  return geminiHooks;
+}
+
+/**
+ * Handle migration from Claude Code
+ */
+export async function handleMigrateFromClaude() {
+  const workingDir = process.cwd();
+
+  // Look for Claude settings in .claude directory
+  const claudeDir = path.join(workingDir, '.claude');
+  const claudeSettingsPath = path.join(claudeDir, 'settings.json');
+  const claudeLocalSettingsPath = path.join(claudeDir, 'settings.local.json');
+
+  let claudeSettings: Record<string, unknown> | null = null;
+  let sourceFile = '';
+
+  // Try to read settings.local.json first, then settings.json
+  if (fs.existsSync(claudeLocalSettingsPath)) {
+    sourceFile = claudeLocalSettingsPath;
+    try {
+      const content = fs.readFileSync(claudeLocalSettingsPath, 'utf-8');
+      claudeSettings = JSON.parse(stripJsonComments(content)) as Record<
+        string,
+        unknown
+      >;
+    } catch (error) {
+      debugLogger.error(
+        `Error reading ${claudeLocalSettingsPath}: ${getErrorMessage(error)}`,
+      );
+    }
+  } else if (fs.existsSync(claudeSettingsPath)) {
+    sourceFile = claudeSettingsPath;
+    try {
+      const content = fs.readFileSync(claudeSettingsPath, 'utf-8');
+      claudeSettings = JSON.parse(stripJsonComments(content)) as Record<
+        string,
+        unknown
+      >;
+    } catch (error) {
+      debugLogger.error(
+        `Error reading ${claudeSettingsPath}: ${getErrorMessage(error)}`,
+      );
+    }
+  } else {
+    debugLogger.error(
+      'No Claude Code settings found in .claude directory. Expected settings.json or settings.local.json',
+    );
+    return;
+  }
+
+  if (!claudeSettings) {
+    return;
+  }
+
+  debugLogger.log(`Found Claude Code settings in: ${sourceFile}`);
+
+  // Migrate hooks
+  const migratedHooks = migrateClaudeHooks(claudeSettings);
+
+  if (Object.keys(migratedHooks).length === 0) {
+    debugLogger.log('No hooks found in Claude Code settings to migrate.');
+    return;
+  }
+
+  debugLogger.log(
+    `Migrating ${Object.keys(migratedHooks).length} hook event(s)...`,
+  );
+
+  // Load current Gemini settings
+  const settings = loadSettings(workingDir);
+
+  // Merge migrated hooks with existing hooks
+  const existingHooks =
+    (settings.merged.hooks as Record<string, unknown>) || {};
+  const mergedHooks = { ...existingHooks, ...migratedHooks };
+
+  // Update settings (setValue automatically saves)
+  try {
+    settings.setValue(SettingScope.Workspace, 'hooks', mergedHooks);
+
+    debugLogger.log('✓ Hooks successfully migrated to .gemini/settings.json');
+    debugLogger.log(
+      '\nMigration complete! Please review the migrated hooks in .gemini/settings.json',
+    );
+    debugLogger.log(
+      'Note: Set tools.enableHooks to true in your settings to enable the hook system.',
+    );
+  } catch (error) {
+    debugLogger.error(`Error saving migrated hooks: ${getErrorMessage(error)}`);
+  }
+}
+
+export const migrateCommand: CommandModule = {
+  command: 'migrate',
+  describe: 'Migrate hooks from Claude Code to Gemini CLI',
+  builder: (yargs) =>
+    yargs.option('from-claude', {
+      describe: 'Migrate from Claude Code hooks',
+      type: 'boolean',
+      default: false,
+    }),
+  handler: async (argv) => {
+    const args = argv as unknown as MigrateArgs;
+    if (args.fromClaude) {
+      await handleMigrateFromClaude();
+    } else {
+      debugLogger.log(
+        'Usage: gemini hooks migrate --from-claude\n\nMigrate hooks from Claude Code to Gemini CLI format.',
+      );
+    }
+    await exitCli();
+  },
+};

packages/cli/src/config/config.ts

@@ -10,6 +10,7 @@ import process from 'node:process';
 import { mcpCommand } from '../commands/mcp.js';
 import type { OutputFormat } from '@google/gemini-cli-core';
 import { extensionsCommand } from '../commands/extensions.js';
+import { hooksCommand } from '../commands/hooks.js';
 import {
   Config,
   setGeminiMdFilename as setServerGeminiMdFilename,
@@ -281,6 +282,11 @@ export async function parseArguments(settings: Settings): Promise<CliArgs> {
     yargsInstance.command(extensionsCommand);
   }
 
+  // Register hooks command if hooks are enabled
+  if (settings?.tools?.enableHooks) {
+    yargsInstance.command(hooksCommand);
+  }
+
   yargsInstance
     .version(await getCliVersion()) // This will enable the --version flag based on package.json
     .alias('v', 'version')

packages/cli/src/config/settings.ts

@@ -38,11 +38,17 @@ import { SettingPaths } from './settingPaths.js';
 function getMergeStrategyForPath(path: string[]): MergeStrategy | undefined {
   let current: SettingDefinition | undefined = undefined;
   let currentSchema: SettingsSchema | undefined = getSettingsSchema();
+  let parent: SettingDefinition | undefined = undefined;
 
   for (const key of path) {
     if (!currentSchema || !currentSchema[key]) {
+      // Key not found in schema - check if parent has additionalProperties
+      if (parent?.additionalProperties?.mergeStrategy) {
+        return parent.additionalProperties.mergeStrategy;
+      }
       return undefined;
     }
+    parent = current;
     current = currentSchema[key];
     currentSchema = current.properties;
   }

packages/cli/src/config/settingsSchema.ts

@@ -14,8 +14,6 @@ import type {
   BugCommandSettings,
   TelemetrySettings,
   AuthType,
-  HookDefinition,
-  HookEventName,
 } from '@google/gemini-cli-core';
 import {
   DEFAULT_TRUNCATE_TOOL_OUTPUT_LINES,
@@ -80,6 +78,11 @@ export interface SettingCollectionDefinition {
    * For example, a JSON schema generator can use this to point to a shared definition.
    */
   ref?: string;
+  /**
+   * Optional merge strategy for dynamically added properties.
+   * Used when this collection definition is referenced via additionalProperties.
+   */
+  mergeStrategy?: MergeStrategy;
 }
 
 export enum MergeStrategy {
@@ -1422,11 +1425,165 @@ const SETTINGS_SCHEMA = {
     label: 'Hooks',
     category: 'Advanced',
     requiresRestart: false,
-    default: {} as { [K in HookEventName]?: HookDefinition[] },
+    default: {},
     description:
       'Hook configurations for intercepting and customizing agent behavior.',
     showInDialog: false,
-    mergeStrategy: MergeStrategy.SHALLOW_MERGE,
+    properties: {
+      disabled: {
+        type: 'array',
+        label: 'Disabled Hooks',
+        category: 'Advanced',
+        requiresRestart: false,
+        default: [] as string[],
+        description:
+          'List of hook names (commands) that should be disabled. Hooks in this list will not execute even if configured.',
+        showInDialog: false,
+        items: {
+          type: 'string',
+          description: 'Hook command name',
+        },
+        mergeStrategy: MergeStrategy.UNION,
+      },
+      BeforeTool: {
+        type: 'array',
+        label: 'Before Tool Hooks',
+        category: 'Advanced',
+        requiresRestart: false,
+        default: [],
+        description:
+          'Hooks that execute before tool execution. Can intercept, validate, or modify tool calls.',
+        showInDialog: false,
+        ref: 'HookDefinitionArray',
+        mergeStrategy: MergeStrategy.CONCAT,
+      },
+      AfterTool: {
+        type: 'array',
+        label: 'After Tool Hooks',
+        category: 'Advanced',
+        requiresRestart: false,
+        default: [],
+        description:
+          'Hooks that execute after tool execution. Can process results, log outputs, or trigger follow-up actions.',
+        showInDialog: false,
+        ref: 'HookDefinitionArray',
+        mergeStrategy: MergeStrategy.CONCAT,
+      },
+      BeforeAgent: {
+        type: 'array',
+        label: 'Before Agent Hooks',
+        category: 'Advanced',
+        requiresRestart: false,
+        default: [],
+        description:
+          'Hooks that execute before agent loop starts. Can set up context or initialize resources.',
+        showInDialog: false,
+        ref: 'HookDefinitionArray',
+        mergeStrategy: MergeStrategy.CONCAT,
+      },
+      AfterAgent: {
+        type: 'array',
+        label: 'After Agent Hooks',
+        category: 'Advanced',
+        requiresRestart: false,
+        default: [],
+        description:
+          'Hooks that execute after agent loop completes. Can perform cleanup or summarize results.',
+        showInDialog: false,
+        ref: 'HookDefinitionArray',
+        mergeStrategy: MergeStrategy.CONCAT,
+      },
+      Notification: {
+        type: 'array',
+        label: 'Notification Hooks',
+        category: 'Advanced',
+        requiresRestart: false,
+        default: [],
+        description:
+          'Hooks that execute on notification events (errors, warnings, info). Can log or alert on specific conditions.',
+        showInDialog: false,
+        ref: 'HookDefinitionArray',
+        mergeStrategy: MergeStrategy.CONCAT,
+      },
+      SessionStart: {
+        type: 'array',
+        label: 'Session Start Hooks',
+        category: 'Advanced',
+        requiresRestart: false,
+        default: [],
+        description:
+          'Hooks that execute when a session starts. Can initialize session-specific resources or state.',
+        showInDialog: false,
+        ref: 'HookDefinitionArray',
+        mergeStrategy: MergeStrategy.CONCAT,
+      },
+      SessionEnd: {
+        type: 'array',
+        label: 'Session End Hooks',
+        category: 'Advanced',
+        requiresRestart: false,
+        default: [],
+        description:
+          'Hooks that execute when a session ends. Can perform cleanup or persist session data.',
+        showInDialog: false,
+        ref: 'HookDefinitionArray',
+        mergeStrategy: MergeStrategy.CONCAT,
+      },
+      PreCompress: {
+        type: 'array',
+        label: 'Pre-Compress Hooks',
+        category: 'Advanced',
+        requiresRestart: false,
+        default: [],
+        description:
+          'Hooks that execute before chat history compression. Can back up or analyze conversation before compression.',
+        showInDialog: false,
+        ref: 'HookDefinitionArray',
+        mergeStrategy: MergeStrategy.CONCAT,
+      },
+      BeforeModel: {
+        type: 'array',
+        label: 'Before Model Hooks',
+        category: 'Advanced',
+        requiresRestart: false,
+        default: [],
+        description:
+          'Hooks that execute before LLM requests. Can modify prompts, inject context, or control model parameters.',
+        showInDialog: false,
+        ref: 'HookDefinitionArray',
+        mergeStrategy: MergeStrategy.CONCAT,
+      },
+      AfterModel: {
+        type: 'array',
+        label: 'After Model Hooks',
+        category: 'Advanced',
+        requiresRestart: false,
+        default: [],
+        description:
+          'Hooks that execute after LLM responses. Can process outputs, extract information, or log interactions.',
+        showInDialog: false,
+        ref: 'HookDefinitionArray',
+        mergeStrategy: MergeStrategy.CONCAT,
+      },
+      BeforeToolSelection: {
+        type: 'array',
+        label: 'Before Tool Selection Hooks',
+        category: 'Advanced',
+        requiresRestart: false,
+        default: [],
+        description:
+          'Hooks that execute before tool selection. Can filter or prioritize available tools dynamically.',
+        showInDialog: false,
+        ref: 'HookDefinitionArray',
+        mergeStrategy: MergeStrategy.CONCAT,
+      },
+    },
+    additionalProperties: {
+      type: 'array',
+      description:
+        'Custom hook event arrays that contain hook definitions for user-defined events',
+      mergeStrategy: MergeStrategy.CONCAT,
+    },
   },
 } as const satisfies SettingsSchema;
 
@@ -1698,6 +1855,46 @@ export const SETTINGS_SCHEMA_DEFINITIONS: Record<
     description: 'Accepts either a boolean flag or a string command name.',
     anyOf: [{ type: 'boolean' }, { type: 'string' }],
   },
+  HookDefinitionArray: {
+    type: 'array',
+    description: 'Array of hook definition objects for a specific event.',
+    items: {
+      type: 'object',
+      description:
+        'Hook definition specifying matcher pattern and hook configurations.',
+      properties: {
+        matcher: {
+          type: 'string',
+          description:
+            'Pattern to match against the event context (tool name, notification type, etc.). Supports exact match, regex (/pattern/), and wildcards (*).',
+        },
+        hooks: {
+          type: 'array',
+          description: 'Hooks to execute when the matcher matches.',
+          items: {
+            type: 'object',
+            description: 'Individual hook configuration.',
+            properties: {
+              type: {
+                type: 'string',
+                description:
+                  'Type of hook (currently only "command" supported).',
+              },
+              command: {
+                type: 'string',
+                description:
+                  'Shell command to execute. Receives JSON input via stdin and returns JSON output via stdout.',
+              },
+              timeout: {
+                type: 'number',
+                description: 'Timeout in milliseconds for hook execution.',
+              },
+            },
+          },
+        },
+      },
+    },
+  },
 };
 
 export function getSettingsSchema(): SettingsSchemaType {

packages/cli/src/services/BuiltinCommandLoader.test.ts

@@ -98,6 +98,7 @@ describe('BuiltinCommandLoader', () => {
       getFolderTrust: vi.fn().mockReturnValue(true),
       getEnableMessageBusIntegration: () => false,
       getEnableExtensionReloading: () => false,
+      getEnableHooks: () => false,
     } as unknown as Config;
 
     restoreCommandMock.mockReturnValue({
@@ -172,6 +173,7 @@ describe('BuiltinCommandLoader', () => {
     const mockConfigWithMessageBus = {
       ...mockConfig,
       getEnableMessageBusIntegration: () => true,
+      getEnableHooks: () => false,
     } as unknown as Config;
     const loader = new BuiltinCommandLoader(mockConfigWithMessageBus);
     const commands = await loader.loadCommands(new AbortController().signal);
@@ -183,6 +185,7 @@ describe('BuiltinCommandLoader', () => {
     const mockConfigWithoutMessageBus = {
       ...mockConfig,
       getEnableMessageBusIntegration: () => false,
+      getEnableHooks: () => false,
     } as unknown as Config;
     const loader = new BuiltinCommandLoader(mockConfigWithoutMessageBus);
     const commands = await loader.loadCommands(new AbortController().signal);
@@ -201,6 +204,7 @@ describe('BuiltinCommandLoader profile', () => {
       getCheckpointingEnabled: () => false,
       getEnableMessageBusIntegration: () => false,
       getEnableExtensionReloading: () => false,
+      getEnableHooks: () => false,
     } as unknown as Config;
   });
 

packages/cli/src/services/BuiltinCommandLoader.ts

@@ -22,6 +22,7 @@ import { directoryCommand } from '../ui/commands/directoryCommand.js';
 import { editorCommand } from '../ui/commands/editorCommand.js';
 import { extensionsCommand } from '../ui/commands/extensionsCommand.js';
 import { helpCommand } from '../ui/commands/helpCommand.js';
+import { hooksCommand } from '../ui/commands/hooksCommand.js';
 import { ideCommand } from '../ui/commands/ideCommand.js';
 import { initCommand } from '../ui/commands/initCommand.js';
 import { mcpCommand } from '../ui/commands/mcpCommand.js';
@@ -72,6 +73,7 @@ export class BuiltinCommandLoader implements ICommandLoader {
       editorCommand,
       extensionsCommand(this.config?.getEnableExtensionReloading()),
       helpCommand,
+      ...(this.config?.getEnableHooks() ? [hooksCommand] : []),
       await ideCommand(),
       initCommand,
       mcpCommand,

packages/cli/src/ui/commands/hooksCommand.test.ts

@@ -0,0 +1,569 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { hooksCommand } from './hooksCommand.js';
+import { createMockCommandContext } from '../../test-utils/mockCommandContext.js';
+import { MessageType } from '../types.js';
+import type { HookRegistryEntry } from '@google/gemini-cli-core';
+import { HookType, HookEventName, ConfigSource } from '@google/gemini-cli-core';
+import type { CommandContext } from './types.js';
+
+describe('hooksCommand', () => {
+  let mockContext: CommandContext;
+  let mockHookSystem: {
+    getAllHooks: ReturnType<typeof vi.fn>;
+    setHookEnabled: ReturnType<typeof vi.fn>;
+    getRegistry: ReturnType<typeof vi.fn>;
+  };
+  let mockConfig: {
+    getHookSystem: ReturnType<typeof vi.fn>;
+  };
+  let mockSettings: {
+    merged: {
+      hooks?: {
+        disabled?: string[];
+      };
+    };
+    setValue: ReturnType<typeof vi.fn>;
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    // Create mock hook system
+    mockHookSystem = {
+      getAllHooks: vi.fn().mockReturnValue([]),
+      setHookEnabled: vi.fn(),
+      getRegistry: vi.fn().mockReturnValue({
+        initialize: vi.fn().mockResolvedValue(undefined),
+      }),
+    };
+
+    // Create mock config
+    mockConfig = {
+      getHookSystem: vi.fn().mockReturnValue(mockHookSystem),
+    };
+
+    // Create mock settings
+    mockSettings = {
+      merged: {
+        hooks: {
+          disabled: [],
+        },
+      },
+      setValue: vi.fn(),
+    };
+
+    // Create mock context with config and settings
+    mockContext = createMockCommandContext({
+      services: {
+        config: mockConfig,
+        settings: mockSettings,
+      },
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('root command', () => {
+    it('should have the correct name and description', () => {
+      expect(hooksCommand.name).toBe('hooks');
+      expect(hooksCommand.description).toBe('Manage hooks');
+    });
+
+    it('should have all expected subcommands', () => {
+      expect(hooksCommand.subCommands).toBeDefined();
+      expect(hooksCommand.subCommands).toHaveLength(3);
+
+      const subCommandNames = hooksCommand.subCommands!.map((cmd) => cmd.name);
+      expect(subCommandNames).toContain('panel');
+      expect(subCommandNames).toContain('enable');
+      expect(subCommandNames).toContain('disable');
+    });
+
+    it('should delegate to panel action when invoked without subcommand', async () => {
+      if (!hooksCommand.action) {
+        throw new Error('hooks command must have an action');
+      }
+
+      mockHookSystem.getAllHooks.mockReturnValue([
+        createMockHook('test-hook', HookEventName.BeforeTool, true),
+      ]);
+
+      await hooksCommand.action(mockContext, '');
+
+      expect(mockContext.ui.addItem).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: MessageType.HOOKS_LIST,
+        }),
+        expect.any(Number),
+      );
+    });
+  });
+
+  describe('panel subcommand', () => {
+    it('should return error when config is not loaded', async () => {
+      const contextWithoutConfig = createMockCommandContext({
+        services: {
+          config: null,
+        },
+      });
+
+      const panelCmd = hooksCommand.subCommands!.find(
+        (cmd) => cmd.name === 'panel',
+      );
+      if (!panelCmd?.action) {
+        throw new Error('panel command must have an action');
+      }
+
+      const result = await panelCmd.action(contextWithoutConfig, '');
+
+      expect(result).toEqual({
+        type: 'message',
+        messageType: 'error',
+        content: 'Config not loaded.',
+      });
+    });
+
+    it('should return info message when hook system is not enabled', async () => {
+      mockConfig.getHookSystem.mockReturnValue(null);
+
+      const panelCmd = hooksCommand.subCommands!.find(
+        (cmd) => cmd.name === 'panel',
+      );
+      if (!panelCmd?.action) {
+        throw new Error('panel command must have an action');
+      }
+
+      const result = await panelCmd.action(mockContext, '');
+
+      expect(result).toEqual({
+        type: 'message',
+        messageType: 'info',
+        content:
+          'Hook system is not enabled. Enable it in settings with tools.enableHooks',
+      });
+    });
+
+    it('should return info message when no hooks are configured', async () => {
+      mockHookSystem.getAllHooks.mockReturnValue([]);
+
+      const panelCmd = hooksCommand.subCommands!.find(
+        (cmd) => cmd.name === 'panel',
+      );
+      if (!panelCmd?.action) {
+        throw new Error('panel command must have an action');
+      }
+
+      const result = await panelCmd.action(mockContext, '');
+
+      expect(result).toEqual({
+        type: 'message',
+        messageType: 'info',
+        content:
+          'No hooks configured. Add hooks to your settings to get started.',
+      });
+    });
+
+    it('should display hooks list when hooks are configured', async () => {
+      const mockHooks: HookRegistryEntry[] = [
+        createMockHook('echo-test', HookEventName.BeforeTool, true),
+        createMockHook('notify', HookEventName.AfterAgent, false),
+      ];
+
+      mockHookSystem.getAllHooks.mockReturnValue(mockHooks);
+
+      const panelCmd = hooksCommand.subCommands!.find(
+        (cmd) => cmd.name === 'panel',
+      );
+      if (!panelCmd?.action) {
+        throw new Error('panel command must have an action');
+      }
+
+      await panelCmd.action(mockContext, '');
+
+      expect(mockContext.ui.addItem).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: MessageType.HOOKS_LIST,
+          hooks: mockHooks,
+        }),
+        expect.any(Number),
+      );
+    });
+  });
+
+  describe('enable subcommand', () => {
+    it('should return error when config is not loaded', async () => {
+      const contextWithoutConfig = createMockCommandContext({
+        services: {
+          config: null,
+        },
+      });
+
+      const enableCmd = hooksCommand.subCommands!.find(
+        (cmd) => cmd.name === 'enable',
+      );
+      if (!enableCmd?.action) {
+        throw new Error('enable command must have an action');
+      }
+
+      const result = await enableCmd.action(contextWithoutConfig, 'test-hook');
+
+      expect(result).toEqual({
+        type: 'message',
+        messageType: 'error',
+        content: 'Config not loaded.',
+      });
+    });
+
+    it('should return error when hook system is not enabled', async () => {
+      mockConfig.getHookSystem.mockReturnValue(null);
+
+      const enableCmd = hooksCommand.subCommands!.find(
+        (cmd) => cmd.name === 'enable',
+      );
+      if (!enableCmd?.action) {
+        throw new Error('enable command must have an action');
+      }
+
+      const result = await enableCmd.action(mockContext, 'test-hook');
+
+      expect(result).toEqual({
+        type: 'message',
+        messageType: 'error',
+        content: 'Hook system is not enabled.',
+      });
+    });
+
+    it('should return error when hook name is not provided', async () => {
+      const enableCmd = hooksCommand.subCommands!.find(
+        (cmd) => cmd.name === 'enable',
+      );
+      if (!enableCmd?.action) {
+        throw new Error('enable command must have an action');
+      }
+
+      const result = await enableCmd.action(mockContext, '');
+
+      expect(result).toEqual({
+        type: 'message',
+        messageType: 'error',
+        content: 'Usage: /hooks enable <hook-name>',
+      });
+    });
+
+    it('should enable a hook and update settings', async () => {
+      // Update the context's settings with disabled hooks
+      mockContext.services.settings.merged.hooks = {
+        disabled: ['test-hook', 'other-hook'],
+      };
+
+      const enableCmd = hooksCommand.subCommands!.find(
+        (cmd) => cmd.name === 'enable',
+      );
+      if (!enableCmd?.action) {
+        throw new Error('enable command must have an action');
+      }
+
+      const result = await enableCmd.action(mockContext, 'test-hook');
+
+      expect(mockContext.services.settings.setValue).toHaveBeenCalledWith(
+        expect.any(String),
+        'hooks.disabled',
+        ['other-hook'],
+      );
+      expect(mockHookSystem.setHookEnabled).toHaveBeenCalledWith(
+        'test-hook',
+        true,
+      );
+      expect(result).toEqual({
+        type: 'message',
+        messageType: 'info',
+        content: 'Hook "test-hook" enabled successfully.',
+      });
+    });
+
+    it('should handle error when enabling hook fails', async () => {
+      mockSettings.setValue.mockImplementationOnce(() => {
+        throw new Error('Failed to save settings');
+      });
+
+      const enableCmd = hooksCommand.subCommands!.find(
+        (cmd) => cmd.name === 'enable',
+      );
+      if (!enableCmd?.action) {
+        throw new Error('enable command must have an action');
+      }
+
+      const result = await enableCmd.action(mockContext, 'test-hook');
+
+      expect(result).toEqual({
+        type: 'message',
+        messageType: 'error',
+        content: 'Failed to enable hook: Failed to save settings',
+      });
+    });
+  });
+
+  describe('disable subcommand', () => {
+    it('should return error when config is not loaded', async () => {
+      const contextWithoutConfig = createMockCommandContext({
+        services: {
+          config: null,
+        },
+      });
+
+      const disableCmd = hooksCommand.subCommands!.find(
+        (cmd) => cmd.name === 'disable',
+      );
+      if (!disableCmd?.action) {
+        throw new Error('disable command must have an action');
+      }
+
+      const result = await disableCmd.action(contextWithoutConfig, 'test-hook');
+
+      expect(result).toEqual({
+        type: 'message',
+        messageType: 'error',
+        content: 'Config not loaded.',
+      });
+    });
+
+    it('should return error when hook system is not enabled', async () => {
+      mockConfig.getHookSystem.mockReturnValue(null);
+
+      const disableCmd = hooksCommand.subCommands!.find(
+        (cmd) => cmd.name === 'disable',
+      );
+      if (!disableCmd?.action) {
+        throw new Error('disable command must have an action');
+      }
+
+      const result = await disableCmd.action(mockContext, 'test-hook');
+
+      expect(result).toEqual({
+        type: 'message',
+        messageType: 'error',
+        content: 'Hook system is not enabled.',
+      });
+    });
+
+    it('should return error when hook name is not provided', async () => {
+      const disableCmd = hooksCommand.subCommands!.find(
+        (cmd) => cmd.name === 'disable',
+      );
+      if (!disableCmd?.action) {
+        throw new Error('disable command must have an action');
+      }
+
+      const result = await disableCmd.action(mockContext, '');
+
+      expect(result).toEqual({
+        type: 'message',
+        messageType: 'error',
+        content: 'Usage: /hooks disable <hook-name>',
+      });
+    });
+
+    it('should disable a hook and update settings', async () => {
+      mockContext.services.settings.merged.hooks = {
+        disabled: [],
+      };
+
+      const disableCmd = hooksCommand.subCommands!.find(
+        (cmd) => cmd.name === 'disable',
+      );
+      if (!disableCmd?.action) {
+        throw new Error('disable command must have an action');
+      }
+
+      const result = await disableCmd.action(mockContext, 'test-hook');
+
+      expect(mockContext.services.settings.setValue).toHaveBeenCalledWith(
+        expect.any(String),
+        'hooks.disabled',
+        ['test-hook'],
+      );
+      expect(mockHookSystem.setHookEnabled).toHaveBeenCalledWith(
+        'test-hook',
+        false,
+      );
+      expect(result).toEqual({
+        type: 'message',
+        messageType: 'info',
+        content: 'Hook "test-hook" disabled successfully.',
+      });
+    });
+
+    it('should return info when hook is already disabled', async () => {
+      // Update the context's settings with the hook already disabled
+      mockContext.services.settings.merged.hooks = {
+        disabled: ['test-hook'],
+      };
+
+      const disableCmd = hooksCommand.subCommands!.find(
+        (cmd) => cmd.name === 'disable',
+      );
+      if (!disableCmd?.action) {
+        throw new Error('disable command must have an action');
+      }
+
+      const result = await disableCmd.action(mockContext, 'test-hook');
+
+      expect(mockContext.services.settings.setValue).not.toHaveBeenCalled();
+      expect(mockHookSystem.setHookEnabled).not.toHaveBeenCalled();
+      expect(result).toEqual({
+        type: 'message',
+        messageType: 'info',
+        content: 'Hook "test-hook" is already disabled.',
+      });
+    });
+
+    it('should handle error when disabling hook fails', async () => {
+      mockContext.services.settings.merged.hooks = {
+        disabled: [],
+      };
+      mockSettings.setValue.mockImplementationOnce(() => {
+        throw new Error('Failed to save settings');
+      });
+
+      const disableCmd = hooksCommand.subCommands!.find(
+        (cmd) => cmd.name === 'disable',
+      );
+      if (!disableCmd?.action) {
+        throw new Error('disable command must have an action');
+      }
+
+      const result = await disableCmd.action(mockContext, 'test-hook');
+
+      expect(result).toEqual({
+        type: 'message',
+        messageType: 'error',
+        content: 'Failed to disable hook: Failed to save settings',
+      });
+    });
+  });
+
+  describe('completion', () => {
+    it('should return empty array when config is not available', () => {
+      const contextWithoutConfig = createMockCommandContext({
+        services: {
+          config: null,
+        },
+      });
+
+      const enableCmd = hooksCommand.subCommands!.find(
+        (cmd) => cmd.name === 'enable',
+      );
+      if (!enableCmd?.completion) {
+        throw new Error('enable command must have completion');
+      }
+
+      const result = enableCmd.completion(contextWithoutConfig, 'test');
+      expect(result).toEqual([]);
+    });
+
+    it('should return empty array when hook system is not enabled', () => {
+      mockConfig.getHookSystem.mockReturnValue(null);
+
+      const enableCmd = hooksCommand.subCommands!.find(
+        (cmd) => cmd.name === 'enable',
+      );
+      if (!enableCmd?.completion) {
+        throw new Error('enable command must have completion');
+      }
+
+      const result = enableCmd.completion(mockContext, 'test');
+      expect(result).toEqual([]);
+    });
+
+    it('should return matching hook names', () => {
+      const mockHooks: HookRegistryEntry[] = [
+        createMockHook('test-hook-1', HookEventName.BeforeTool, true),
+        createMockHook('test-hook-2', HookEventName.AfterTool, true),
+        createMockHook('other-hook', HookEventName.AfterAgent, false),
+      ];
+
+      mockHookSystem.getAllHooks.mockReturnValue(mockHooks);
+
+      const enableCmd = hooksCommand.subCommands!.find(
+        (cmd) => cmd.name === 'enable',
+      );
+      if (!enableCmd?.completion) {
+        throw new Error('enable command must have completion');
+      }
+
+      const result = enableCmd.completion(mockContext, 'test');
+      expect(result).toEqual(['test-hook-1', 'test-hook-2']);
+    });
+
+    it('should return all hook names when partial is empty', () => {
+      const mockHooks: HookRegistryEntry[] = [
+        createMockHook('hook-1', HookEventName.BeforeTool, true),
+        createMockHook('hook-2', HookEventName.AfterTool, true),
+      ];
+
+      mockHookSystem.getAllHooks.mockReturnValue(mockHooks);
+
+      const enableCmd = hooksCommand.subCommands!.find(
+        (cmd) => cmd.name === 'enable',
+      );
+      if (!enableCmd?.completion) {
+        throw new Error('enable command must have completion');
+      }
+
+      const result = enableCmd.completion(mockContext, '');
+      expect(result).toEqual(['hook-1', 'hook-2']);
+    });
+
+    it('should handle hooks without command name gracefully', () => {
+      const mockHooks: HookRegistryEntry[] = [
+        createMockHook('test-hook', HookEventName.BeforeTool, true),
+        {
+          ...createMockHook('', HookEventName.AfterTool, true),
+          config: { command: '', type: HookType.Command, timeout: 30 },
+        },
+      ];
+
+      mockHookSystem.getAllHooks.mockReturnValue(mockHooks);
+
+      const enableCmd = hooksCommand.subCommands!.find(
+        (cmd) => cmd.name === 'enable',
+      );
+      if (!enableCmd?.completion) {
+        throw new Error('enable command must have completion');
+      }
+
+      const result = enableCmd.completion(mockContext, 'test');
+      expect(result).toEqual(['test-hook']);
+    });
+  });
+});
+
+/**
+ * Helper function to create a mock HookRegistryEntry
+ */
+function createMockHook(
+  command: string,
+  eventName: HookEventName,
+  enabled: boolean,
+): HookRegistryEntry {
+  return {
+    config: {
+      command,
+      type: HookType.Command,
+      timeout: 30,
+    },
+    source: ConfigSource.Project,
+    eventName,
+    matcher: undefined,
+    sequential: false,
+    enabled,
+  };
+}

packages/cli/src/ui/commands/hooksCommand.ts

@@ -0,0 +1,250 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  SlashCommand,
+  CommandContext,
+  MessageActionReturn,
+} from './types.js';
+import { CommandKind } from './types.js';
+import { MessageType, type HistoryItemHooksList } from '../types.js';
+import type { HookRegistryEntry } from '@google/gemini-cli-core';
+import { getErrorMessage } from '@google/gemini-cli-core';
+import { SettingScope } from '../../config/settings.js';
+
+/**
+ * Display a formatted list of hooks with their status
+ */
+async function panelAction(
+  context: CommandContext,
+): Promise<void | MessageActionReturn> {
+  const { config } = context.services;
+  if (!config) {
+    return {
+      type: 'message',
+      messageType: 'error',
+      content: 'Config not loaded.',
+    };
+  }
+
+  const hookSystem = config.getHookSystem();
+  if (!hookSystem) {
+    return {
+      type: 'message',
+      messageType: 'info',
+      content:
+        'Hook system is not enabled. Enable it in settings with tools.enableHooks',
+    };
+  }
+
+  const allHooks = hookSystem.getAllHooks();
+  if (allHooks.length === 0) {
+    return {
+      type: 'message',
+      messageType: 'info',
+      content:
+        'No hooks configured. Add hooks to your settings to get started.',
+    };
+  }
+
+  const hooksListItem: HistoryItemHooksList = {
+    type: MessageType.HOOKS_LIST,
+    hooks: allHooks,
+  };
+
+  context.ui.addItem(hooksListItem, Date.now());
+}
+
+/**
+ * Enable a hook by name
+ */
+async function enableAction(
+  context: CommandContext,
+  args: string,
+): Promise<void | MessageActionReturn> {
+  const { config } = context.services;
+  if (!config) {
+    return {
+      type: 'message',
+      messageType: 'error',
+      content: 'Config not loaded.',
+    };
+  }
+
+  const hookSystem = config.getHookSystem();
+  if (!hookSystem) {
+    return {
+      type: 'message',
+      messageType: 'error',
+      content: 'Hook system is not enabled.',
+    };
+  }
+
+  const hookName = args.trim();
+  if (!hookName) {
+    return {
+      type: 'message',
+      messageType: 'error',
+      content: 'Usage: /hooks enable <hook-name>',
+    };
+  }
+
+  // Get current disabled hooks from settings
+  const settings = context.services.settings;
+  const disabledHooks = settings.merged.hooks?.disabled || ([] as string[]);
+
+  // Remove from disabled list if present
+  const newDisabledHooks = disabledHooks.filter(
+    (name: string) => name !== hookName,
+  );
+
+  // Update settings (setValue automatically saves)
+  try {
+    settings.setValue(SettingScope.User, 'hooks.disabled', newDisabledHooks);
+
+    // Enable in hook system
+    hookSystem.setHookEnabled(hookName, true);
+
+    return {
+      type: 'message',
+      messageType: 'info',
+      content: `Hook "${hookName}" enabled successfully.`,
+    };
+  } catch (error) {
+    return {
+      type: 'message',
+      messageType: 'error',
+      content: `Failed to enable hook: ${getErrorMessage(error)}`,
+    };
+  }
+}
+
+/**
+ * Disable a hook by name
+ */
+async function disableAction(
+  context: CommandContext,
+  args: string,
+): Promise<void | MessageActionReturn> {
+  const { config } = context.services;
+  if (!config) {
+    return {
+      type: 'message',
+      messageType: 'error',
+      content: 'Config not loaded.',
+    };
+  }
+
+  const hookSystem = config.getHookSystem();
+  if (!hookSystem) {
+    return {
+      type: 'message',
+      messageType: 'error',
+      content: 'Hook system is not enabled.',
+    };
+  }
+
+  const hookName = args.trim();
+  if (!hookName) {
+    return {
+      type: 'message',
+      messageType: 'error',
+      content: 'Usage: /hooks disable <hook-name>',
+    };
+  }
+
+  // Get current disabled hooks from settings
+  const settings = context.services.settings;
+  const disabledHooks = settings.merged.hooks?.disabled || ([] as string[]);
+
+  // Add to disabled list if not already present
+  if (!disabledHooks.includes(hookName)) {
+    const newDisabledHooks = [...disabledHooks, hookName];
+
+    // Update settings (setValue automatically saves)
+    try {
+      settings.setValue(SettingScope.User, 'hooks.disabled', newDisabledHooks);
+
+      // Disable in hook system
+      hookSystem.setHookEnabled(hookName, false);
+
+      return {
+        type: 'message',
+        messageType: 'info',
+        content: `Hook "${hookName}" disabled successfully.`,
+      };
+    } catch (error) {
+      return {
+        type: 'message',
+        messageType: 'error',
+        content: `Failed to disable hook: ${getErrorMessage(error)}`,
+      };
+    }
+  } else {
+    return {
+      type: 'message',
+      messageType: 'info',
+      content: `Hook "${hookName}" is already disabled.`,
+    };
+  }
+}
+
+/**
+ * Completion function for hook names
+ */
+function completeHookNames(
+  context: CommandContext,
+  partialArg: string,
+): string[] {
+  const { config } = context.services;
+  if (!config) return [];
+
+  const hookSystem = config.getHookSystem();
+  if (!hookSystem) return [];
+
+  const allHooks = hookSystem.getAllHooks();
+  const hookNames = allHooks.map((hook) => getHookDisplayName(hook));
+  return hookNames.filter((name) => name.startsWith(partialArg));
+}
+
+/**
+ * Get a display name for a hook
+ */
+function getHookDisplayName(hook: HookRegistryEntry): string {
+  return hook.config.command || 'unknown-hook';
+}
+
+const panelCommand: SlashCommand = {
+  name: 'panel',
+  altNames: ['list', 'show'],
+  description: 'Display all registered hooks with their status',
+  kind: CommandKind.BUILT_IN,
+  action: panelAction,
+};
+
+const enableCommand: SlashCommand = {
+  name: 'enable',
+  description: 'Enable a hook by name',
+  kind: CommandKind.BUILT_IN,
+  action: enableAction,
+  completion: completeHookNames,
+};
+
+const disableCommand: SlashCommand = {
+  name: 'disable',
+  description: 'Disable a hook by name',
+  kind: CommandKind.BUILT_IN,
+  action: disableAction,
+  completion: completeHookNames,
+};
+
+export const hooksCommand: SlashCommand = {
+  name: 'hooks',
+  description: 'Manage hooks',
+  kind: CommandKind.BUILT_IN,
+  subCommands: [panelCommand, enableCommand, disableCommand],
+  action: async (context: CommandContext) => panelCommand.action!(context, ''),
+};

packages/cli/src/ui/components/HistoryItemDisplay.tsx

@@ -30,6 +30,7 @@ import { getMCPServerStatus } from '@google/gemini-cli-core';
 import { ToolsList } from './views/ToolsList.js';
 import { McpStatus } from './views/McpStatus.js';
 import { ChatList } from './views/ChatList.js';
+import { HooksList } from './views/HooksList.js';
 import { ModelMessage } from './messages/ModelMessage.js';
 
 interface HistoryItemDisplayProps {
@@ -158,6 +159,9 @@ export const HistoryItemDisplay: React.FC<HistoryItemDisplayProps> = ({
       {itemForDisplay.type === 'chat_list' && (
         <ChatList chats={itemForDisplay.chats} />
       )}
+      {itemForDisplay.type === 'hooks_list' && (
+        <HooksList hooks={itemForDisplay.hooks} />
+      )}
     </Box>
   );
 };

packages/cli/src/ui/components/views/HooksList.tsx

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type React from 'react';
+import { Box, Text } from 'ink';
+
+interface HooksListProps {
+  hooks: ReadonlyArray<{
+    config: { command?: string; type: string; timeout?: number };
+    source: string;
+    eventName: string;
+    matcher?: string;
+    sequential?: boolean;
+    enabled: boolean;
+  }>;
+}
+
+export const HooksList: React.FC<HooksListProps> = ({ hooks }) => {
+  if (hooks.length === 0) {
+    return (
+      <Box marginTop={1} marginBottom={1}>
+        <Text>No hooks configured.</Text>
+      </Box>
+    );
+  }
+
+  // Group hooks by event name for better organization
+  const hooksByEvent = hooks.reduce(
+    (acc, hook) => {
+      if (!acc[hook.eventName]) {
+        acc[hook.eventName] = [];
+      }
+      acc[hook.eventName].push(hook);
+      return acc;
+    },
+    {} as Record<string, Array<(typeof hooks)[number]>>,
+  );
+
+  return (
+    <Box flexDirection="column" marginTop={1} marginBottom={1}>
+      <Text bold>Configured Hooks:</Text>
+      <Box flexDirection="column" paddingLeft={2} marginTop={1}>
+        {Object.entries(hooksByEvent).map(([eventName, eventHooks]) => (
+          <Box key={eventName} flexDirection="column" marginBottom={1}>
+            <Text color="cyan" bold>
+              {eventName}:
+            </Text>
+            <Box flexDirection="column" paddingLeft={2}>
+              {eventHooks.map((hook, index) => {
+                const hookName = hook.config.command || 'unknown';
+                const statusColor = hook.enabled ? 'green' : 'gray';
+                const statusText = hook.enabled ? 'enabled' : 'disabled';
+
+                return (
+                  <Box key={`${eventName}-${index}`} flexDirection="column">
+                    <Box>
+                      <Text>
+                        <Text color="yellow">{hookName}</Text>
+                        <Text color={statusColor}>{` [${statusText}]`}</Text>
+                      </Text>
+                    </Box>
+                    <Box paddingLeft={2} flexDirection="column">
+                      <Text dimColor>
+                        Source: {hook.source}
+                        {hook.matcher && ` | Matcher: ${hook.matcher}`}
+                        {hook.sequential && ` | Sequential`}
+                        {hook.config.timeout &&
+                          ` | Timeout: ${hook.config.timeout}s`}
+                      </Text>
+                    </Box>
+                  </Box>
+                );
+              })}
+            </Box>
+          </Box>
+        ))}
+      </Box>
+      <Box marginTop={1}>
+        <Text dimColor>
+          Tip: Use `/hooks enable {'<hook-name>'}` or `/hooks disable{' '}
+          {'<hook-name>'}` to toggle hooks
+        </Text>
+      </Box>
+    </Box>
+  );
+};

packages/cli/src/ui/types.ts

@@ -240,6 +240,18 @@ export type HistoryItemMcpStatus = HistoryItemBase & {
   showSchema: boolean;
 };
 
+export type HistoryItemHooksList = HistoryItemBase & {
+  type: 'hooks_list';
+  hooks: Array<{
+    config: { command?: string; type: string; timeout?: number };
+    source: string;
+    eventName: string;
+    matcher?: string;
+    sequential?: boolean;
+    enabled: boolean;
+  }>;
+};
+
 // Using Omit<HistoryItem, 'id'> seems to have some issues with typescript's
 // type inference e.g. historyItem.type === 'tool_group' isn't auto-inferring that
 // 'tools' in historyItem.
@@ -264,7 +276,8 @@ export type HistoryItemWithoutId =
   | HistoryItemExtensionsList
   | HistoryItemToolsList
   | HistoryItemMcpStatus
-  | HistoryItemChatList;
+  | HistoryItemChatList
+  | HistoryItemHooksList;
 
 export type HistoryItem = HistoryItemWithoutId & { id: number };
 
@@ -286,6 +299,7 @@ export enum MessageType {
   TOOLS_LIST = 'tools_list',
   MCP_STATUS = 'mcp_status',
   CHAT_LIST = 'chat_list',
+  HOOKS_LIST = 'hooks_list',
 }
 
 // Simplified message structure for internal feedback

packages/cli/src/utils/deepMerge.test.ts

@@ -160,4 +160,43 @@ describe('customDeepMerge', () => {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     expect(({} as any).polluted).toBeUndefined();
   });
+
+  it('should use additionalProperties merge strategy for dynamic properties', () => {
+    // Simulates how hooks work: hooks.disabled uses UNION, but hooks.BeforeTool (dynamic) uses CONCAT
+    const target = {
+      hooks: {
+        BeforeTool: [{ command: 'user-hook-1' }, { command: 'user-hook-2' }],
+        disabled: ['hook-a'],
+      },
+    };
+    const source = {
+      hooks: {
+        BeforeTool: [{ command: 'workspace-hook-1' }],
+        disabled: ['hook-b'],
+      },
+    };
+
+    // Mock the getMergeStrategyForPath behavior for hooks
+    const getMergeStrategy = (path: string[]) => {
+      const p = path.join('.');
+      // hooks.disabled uses UNION strategy (explicitly defined in schema)
+      if (p === 'hooks.disabled') return MergeStrategy.UNION;
+      // hooks.BeforeTool uses CONCAT strategy (via additionalProperties)
+      if (p === 'hooks.BeforeTool') return MergeStrategy.CONCAT;
+      return undefined;
+    };
+
+    const result = customDeepMerge(getMergeStrategy, target, source);
+
+    // BeforeTool should concatenate
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect((result as any)['hooks']['BeforeTool']).toEqual([
+      { command: 'user-hook-1' },
+      { command: 'user-hook-2' },
+      { command: 'workspace-hook-1' },
+    ]);
+    // disabled should union (deduplicate)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect((result as any)['hooks']['disabled']).toEqual(['hook-a', 'hook-b']);
+  });
 });