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