Hooks Creator

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).

1. 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?"

1. 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).

1. Dependency Checks (MANDATORY):

• Bash: Verify jq availability AND functionality.
• Pattern: command -v jq >/dev/null 2>&1 || { echo "jq is required" >&2; exit 2; }

1. 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".

1. Verification Recommendations:

• Tell the user to run chmod +x .
• 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. |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MatrixFounder
• Source: MatrixFounder/Universal-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.