Feature: Comprehensive Hooking System

[Edilmo]

Summary

The Gemini CLI Hooks v1 Feature introduces a first‑class hook system that lets developers intercept key lifecycle events in the Gemini agent loop. It mirrors the JSON‑over‑stdin contract, exit code semantics and matcher syntax used by Claude Code, aligns conceptually with Google’s ADK callbacks, and adds new events like BeforeModel and BeforeToolSelection for advanced prompt engineering and tool planning. The system supports two hook types: command hooks for running arbitrary scripts, and plugin hooks that load npm packages implementing a stable interface with dependency injection. Configuration can live at project, user, system and extension levels, with well‑defined precedence. Migration tooling converts existing Claude Code hooks into the new format, and dedicated CLI commands manage installation, reloading and execution of hooks.

Motivation

Today, customizing Gemini CLI behaviour requires editing core code or complex workarounds. There is no unified mechanism to inject dynamic context, enforce security guardrails, log interactions or optimise tool selection. Additionally, users with existing Claude Code scripts face friction when migrating their workflows, and there is no way to distribute reusable hook logic as npm packages. A robust hook system will:

• Allow users to augment prompts, filter or reorder tools, sanitise LLM responses and implement guardrails without modifying the core.
• Provide feature parity with Claude Code hooks so existing scripts run unmodified.
• Enable third‑party developers to share and reuse logic via npm packages with a well‑defined plugin interface.
• Lay the foundation for future integration with ADK callbacks and extension workflows.
• Increase confidence and visibility by offering observability, configuration precedence and safe‑mode execution.

Core Features

1. Event Framework & Contracts – Define a set of events (BeforeTool, AfterTool, BeforeAgent, Notification, AfterAgent, SessionStart/End, PreCompress, BeforeModel, AfterModel, BeforeToolSelection) with clear JSON input/output schemas. Support matchers (exact, regex, wildcard) and precedence across project, user, system and extension scopes.
2. Command & Plugin Hooks – Support two hook types:
   • Command hooks, which run shell commands and communicate via exit codes and stdin/stdout.
   • Plugin hooks, which discover and load npm packages labelled with geminicli-plugin, validate their declared API version and inject services (Logger, Config, HttpClient) into their hook methods. The design uses dependency injection to avoid global state and ensure loose coupling.
3. Advanced Events – Introduce BeforeModel to modify or replace the LLM request/response and BeforeToolSelection to adjust the candidate tool list before the planner runs, enabling sophisticated prompt augmentation and tool optimisation.
4. Configuration & Management – Merge hook definitions from .gemini/settings.json, user‑level and system‑level configs, and gemini-extension.json, with project settings overriding user and system settings. Provide commands like gemini hooks install <package>, gemini hooks uninstall, /hooks reload, /hooks enable, and gemini hooks migrate --from-claude to manage hooks and plugins.
5. Observability – Log every hook invocation with event name, hook type, duration and result and expose a /hooks panel listing active hooks.
6. Extension & Migration Support – Allow extensions to declare hooks that run after project/user/system hooks; publish TypeScript definitions for plugin interfaces; provide a migration command that reads .claudeconfigurations and converts them to .gemini format, converting environment variables like CLAUDE_PROJECT_DIR into GEMINI_PROJECT_DIR for compatibility.

[gemini-cli]

This issue is a feature request for a new hooking system, which falls under the extensibility area. As a new feature, it is assigned a medium priority.