Hooks and Integrations
Gemini CLI
Agentinel integrates with Google's Gemini CLI via its preToolCall lifecycle hook, which fires before any tool invocation, including shell command execution.
How the hook works
Gemini CLI uses a tool-call architecture where all agent actions, including running shell commands, are modeled as structured tool invocations. The preToolCall hook is called before any tool is executed, with the tool name and arguments available in the hook context.
Agentinel registers as the preToolCall handler scoped to the run_shell_command tool type. When it detects an npm install, it extracts the package names, runs the OSV scan, and returns a structured decision payload.
If the decision is BLOCK in strict mode, Agentinel exits with code 1 and Gemini CLI cancels the tool call, returning the block reason to the model context so Gemini can self-correct.
Generated Gemini config
Running npx asen init writes to .gemini/config.json in your project root:
{
"hooks": {
"preToolCall": {
"matcher": "run_shell_command",
"command": "npx agentinel-hook --agent gemini"
}
}
}The matcher field scopes the hook to only shell command tool calls. Other Gemini tool types (file operations, web search, etc.) are not intercepted.
What a block looks like in Gemini CLI
When a package is blocked, Agentinel returns a structured payload and Gemini CLI surfaces it in its output before returning the block reason to the model:
Tool call: run_shell_command
args: { "command": "npm install axios-extended-pro" }
[agentinel] BLOCKED: axios-extended-pro
Reason: Package does not exist on npm (hallucination).
preToolCall hook exited with code 1. Tool call cancelled.
Gemini: The package axios-extended-pro was blocked by Agentinel because it doesn't
exist on npm. You likely want axios instead.{
"hookEvent": "preToolCall",
"tool": "run_shell_command",
"action": "BLOCK",
"package": "axios-extended-pro",
"reason": "agentinel blocked axios-extended-pro: Package does not exist on npm (hallucination)."
}Gemini model self-correction
One advantage of the Gemini CLI's tool-call architecture is that the block reason is automatically injected back into the model's context. This means Gemini will attempt to self-correct by looking up the correct package name, rather than simply stopping.
Self-correction loop
When Agentinel returns a BLOCK with a reason of "does not exist on npm", Gemini typically responds by searching for the correct package name and retrying with a corrected install command, which Agentinel then re-scans.
Gemini CLI specific notes
- Gemini CLI passes the full tool call arguments as a JSON object. Agentinel reads the command field and parses it for npm install calls.
- The preToolCall hook fires for every tool call, not just shell commands. The matcher field in the config limits it to run_shell_command only.
- Gemini CLI is authenticated via Google Cloud or an API key. Agentinel does not interact with any Google authentication.
- In warn mode, the block reason is still injected into context, but the tool call is allowed to proceed. Gemini may choose to retry or continue.