hooks-creator

name	hooks-creator
description	Use when the user wants to customize Gemini CLI behavior using hooks (events, blockers, loggers).
tier	2
version	1

Hooks Creator

Purpose: Create robust, secure, and compliant Gemini CLI hooks that intercept and customize the agent's lifecycle (e.g., blocking tools, injecting context, logging).

[!WARNING] SECURITY CRITICAL:

• Strict JSON: Printing to stdout breaks the CLI. Use stderr for logs.
• Injection Risks: BASH hooks MUST use jq. Never use grep on raw input.
• Dependency Checks: Scripts MUST fail gracefully (exit 2) if deps like jq are missing.

1. Red Flags (Anti-Rationalization)

STOP and READ THIS if you are thinking:

• "I'll use grep to parse JSON in Bash because it's faster" -> WRONG. This is a security vulnerability. You MUST use jq.
• "I'll just print a debug message to stdout" -> WRONG. This breaks JSON parsing. ALL logs must go to stderr.
• "I can skip the dependency check" -> WRONG. Scripts will fail silently. functionality. Always check for jq or node modules.
• "I'll use exit 1 for a denial" -> WRONG. Use exit 0 with {"decision": "deny"} for structured feedback, or exit 2 for system errors.

2. Capabilities

• Generate Bash hooks for simple logic (using jq).
• Generate Node.js hooks for complex logic or heavy JSON processing.
• Configure settings.json with correct matchers and event types.
• Validate security and performance best practices.

3. Instruction Protocol

Phase 1: Analyze & Clarify

1. Identify the Event: Map user intent to the correct Life Cycle Event.
   • Example: "Stop me from committing secrets" -> BeforeTool (triggered on write_file).
   • Example: "Add git history to context" -> BeforeAgent (or SessionStart).
   • Example: "Add git history to context" -> BeforeAgent (or SessionStart).
2. Analyize Clarity (Fast Path):
   • Clear Request: If the user provides specific intent (e.g., "Block 'rm' commands"), SKIP clarification and proceed to implementation.
   • Ambiguous Request: If vague (e.g., "Make it safer"), ask ONE clarifying question: "Do you want to block specific tools or scan content?"
3. Select Implementation:
   • Bash: For simple checks (grepping specific patterns, file existence).
   • Node.js: For logic requiring array manipulation, complex JSON, or async calls.

Phase 2: Implementation (The Golden Rules)

1. Strict JSON Output:
   • The script MUST NOT echo anything to stdout except the final JSON object.
   • Redirect all intermediate logs to stderr (e.g., echo "Debug" >&2).
   • Redirect all intermediate logs to stderr (e.g., echo "Debug" >&2).
2. Dependency Checks (MANDATORY):
   • Bash: Verify jq availability AND functionality.
     • Pattern: command -v jq >/dev/null 2>&1 || { echo "jq is required" >&2; exit 2; }
3. Security Sanitization:
   • Never pass raw input to eval or exec.
   • Use jq to extract fields safely before processing.

Phase 3: Configuration & Verification

1. Generate settings.json snippet:
   • Use specific matchers (e.g., write_file|replace_...) instead of * to optimize performance.
   • Ensure type is "command".
2. Verification Recommendations:
   • Tell the user to run chmod +x <script>.
   • Advise testing with piped JSON: cat test.json | ./hook.sh.

4. Canonical Resources (Source of Truth)

You MUST read these files for API details:

• references/Gemini CLI Hooks.md (Core Concepts)
• references/reference.md (JSON Schema & Exit Codes)
• references/best-practices.md (Security)

5. Examples (Few-Shot)

1. Security Gate (Bash)

See examples/security_gate.sh for full implementation. Use when: Blocking unsafe content or tools.

1. Security Gate (Bash)

See examples/security_gate.sh for full implementation. Use when: Blocking unsafe content or tools.

2. Tool Filtering (Node.js)

See examples/tool_filter.js for full implementation. Use when: Restricting tools based on user prompt/intent.

3. Settings Configuration

See examples/settings_snippet.json.

4. Simple Logger (Bash)

See examples/log_tools.sh. Use when: Debugging or auditing tool usage.

5. Context Injection (Bash)

See examples/inject_context.sh. Use when: Adding environment data (Git, DB) to agent context.

6. Response Validation (Node.js)

See examples/validate_response.js. Use when: Enforcing quality checks (e.g., "Must include Summary:") before showing output.

6. Rationalization Table

Agent Excuse	Reality / Counter-Argument
"I'll skip the jq check"	Systems without jq will crash unpredictably.
"Users know not to echo"	No they don't. You must enforce it in the code.
"I'll use Python"	Node.js/Bash are preferred for minimal runtime deps, but Python is allowed if requested.