A
argbe.tech - news
1min read

Gemini CLI Hooks API: gate agent tools with BeforeTool matchers

Gemini CLI added synchronous hooks that can intercept tool calls (like write_file or replace) to inject context, validate actions, and enforce local security policies.

Gemini CLI hooks let developers intercept agent tool execution with a BeforeTool matcher (for tools like write_file or replace) to enforce local security policies.

  • Hooks run synchronously inside the agent lifecycle, enabling context injection, action validation, and policy enforcement before a step completes.
  • Hook configuration lives in .gemini/settings.json, where a JSON structure defines matchers, hook types, and the script path to run.
  • Matchers support regular expressions (for example, targeting write_file|replace) so you can scope enforcement to specific high-risk tools.
  • Hook scripts can return structured JSON (including a decision to allow or deny, a reason, and an optional system message) to steer the agent’s next move.
  • Local hook script paths resolve via the $GEMINI_PROJECT_DIR environment variable, keeping workflows portable across machines.