DOCSEARCHbyAlgolia
Submit Docs

Dippy

repository·main·Indexed 42 days ago

https://github.com/ldayton/dippy

An approval autopilot for Claude Code that automatically allows safe, non-destructive shell commands (such as `ls` or `git status`) while prompting for approval or providing guidance for potentially dangerous operations like `rm -rf` or secret file writes. Version 0.2.7.

Tokens
70.3K
Snippets
169
Records
277
Agent score
53%

What's inside Dippy

  1. Overview of the Gemini CLI Hook System

    main

    Gemini CLI hooks are scripts or programs executed at specific points in the agentic loop. They allow you to intercept and customize behavior (such as blocking tools, modifying inputs, or injecting context) without modifying the CLI source code.

    Key Technical Details:

    • Execution: Hooks run synchronously within the agent loop.
    • Communication: Data is exchanged using JSON over stdin/stdout.
    • Signaling: Hooks use exit codes to signal behavior to the CLI.
    • Compatibility: The system mirrors the contract used by Claude Code.

  2. Overview of Agent and Tab Hook Types

    main

    Hooks are categorized by when they trigger in the Cursor lifecycle.

    Agent Hooks (Cmd+K / Agent Chat)

    These hooks interact with the LLM agent loop.

    HookTriggerCan Block?Can Message Agent?
    beforeSubmitPromptBefore prompt sent to LLMYesNo (beta limitation)
    beforeShellExecutionBefore shell command runsYesYes
    afterShellExecutionAfter shell command completesNoNo
    beforeMCPExecutionBefore MCP tool invocationYesYes
    afterMCPExecutionAfter MCP tool returnsNoNo
    beforeReadFileBefore file content sent to LLMYesNo
    afterFileEditAfter agent edits a fileNoNo
    afterAgentResponseAfter agent text responseNoNo
    afterAgentThoughtAfter agent thinking/reasoningNoNo
    stopWhen agent loop completesNoYes (followup)

    Tab Hooks (Inline Completions)

    These fire frequently during cursor movement and have performance implications.

    HookTriggerCan Block?
    beforeTabFileReadBefore file read for Tab completionsYes
    afterTabFileEditAfter Tab applies an editNo

  3. Understand hook visibility and context fields

    main

    When configuring hooks, note how different fields are presented to the user or the AI:

    FieldVisibility
    systemMessageShown to the user only
    permissionDecisionReasonShown to Claude (on deny)
    additionalContextShown to Claude (specifically for UserPromptSubmit)

    Note: There is currently no field to inject a message to Claude while simultaneously allowing an operation.

  4. Execution Models of AI Assistant Hook Systems

    main

    Different AI assistants handle hook execution differently. Understanding these models is critical to avoid race conditions or unexpected behavior.

    AspectClaude CodeCursorGemini CLICodex CLI
    ExecutionParallel (all matching)Sequential (first only*)SynchronousN/A
    Hook orderingNon-deterministicFirst in arrayConcatenated by priorityN/A
    Conflicting decisionsLast write wins (undefined)N/ANot documentedN/A
    Default timeout60s (command), 30s (prompt)Not documented60sN/A
    Max timeoutConfigurableNot documentedConfigurableN/A

    *Note: Cursor has a known bug where only the first hook in an array executes.

  5. Configure Approval Policies

    main

    Approval policies determine when Codex must pause and ask for human permission before executing a command.

    Available Policies

    PolicyBehaviorRisk Level
    untrustedAlways ask before any actionSafest
    on-failureAsk only after command failsModerate
    on-requestAsk only when agent requestsBalanced
    neverNever ask for approvalDangerous

    Usage

    # Set via CLI flag
codex --ask-for-approval on-request

# Shortcut for 'on-request' + 'workspace-write' mode
codex --full-auto

# Bypass all safety mechanisms (Use ONLY in isolated environments like VMs)
codex --dangerously-bypass-approvals-and-sandbox
# or
codex --yolo
    codex --ask-for-approval on-request

  7. Security: Workspace Trust and Sandboxing

    main

    Workspace Trust

    Cursor disables VS Code's Workspace Trust by default. To prevent malicious tasks.json files from executing automatically, you can enable it via settings or MDM:

    {
  "security.workspace.trust.enabled": true
}

    Sandbox Mode Limitations

    Sandbox mode (v2.0+) restricts terminal commands by blocking network access by default and limiting file access to the workspace and /tmp.

    Warning: Sandbox mode allows reading sensitive files (e.g., ~/.ssh/id_rsa) even while blocking writes. Use beforeShellExecution hooks to explicitly block access to sensitive paths.

  8. Unique Hook Features by Platform

    main

    Each platform offers distinct specialized hooks that can be leveraged for advanced automation.

    • Claude Code: Supports LLM-evaluated hooks (type: prompt) and subagent lifecycle hooks (SubagentStart/SubagentStop).
    • Cursor: Supports tab completion hooks (beforeTabFileRead) and agent thought hooks (afterAgentThought), plus automatic follow-up messages (max 5).
    • Gemini CLI: Supports model-level hooks (BeforeModel/AfterModel), tool selection hooks (BeforeToolSelection), and extension/plugin hooks via NPM packages.
    • Codex CLI: Primarily uses a skills system (agentskills.io) and lacks a traditional hook system beyond basic notifications.

  9. Use the Permission System to control Agent actions

    main

    Certain hooks (like beforeShellExecution and beforeMCPExecution) allow you to intercept and control agent actions using a permission system.

    Permission Values

    • allow: Execute without user intervention.
    • deny: Block execution and show a user_message.
    • ask: Prompt the user for confirmation.

    Supported Response Fields

    When returning JSON from a blocking hook, use these fields:

    • permission: One of allow, deny, or ask.
    • user_message: Text displayed in the Cursor UI to the user.
    • agent_message: Text injected into the agent's context (Note: subject to known regressions in some versions).
    • continue: (For beforeSubmitPrompt) Boolean to proceed.
    • followup_message: (For stop) An auto-submitted prompt.

  10. Important Cursor Hook Constraints and Gotchas

    main

    When developing Cursor hooks, be aware of these technical limitations and behaviors:

    • stdout is Reserved: Do not use console.log for debugging. console.log is used to send the permission response to Cursor. Use console.error to send debug information to the Hooks output panel.
    • No Hot Reload: You must restart Cursor for any changes to hooks.json to take effect.
    • afterFileEdit is Non-Blocking: This hook is "fire-and-forget". You cannot block an edit, communicate with the user, or send messages to the agent using this hook.
    • Empty cwd Handling: The cwd field in beforeShellExecution may be an empty string. Always provide a fallback to the first workspace root:
      cwd=$(echo "$input" | jq -r '.cwd // empty')
if [[ -z "$cwd" ]]; then
  cwd=$(echo "$input" | jq -r '.workspace_roots[0]')
fi
    • Tab Hook Limitations: Tab hooks (beforeTabFileRead, afterTabFileEdit) do not include the attachments field.
    • beforeSubmitPrompt (Beta): In its current beta state, Cursor does not respect output JSON from this hook; it is currently for recording only.
    • Follow-up Limits: The stop hook's followup_message is limited to 5 automatic submissions to prevent infinite loops.

  11. How Claude Code hooks execute

    main

    Claude Code hooks execute in parallel and are asynchronous. When multiple hooks match a single event, they all run simultaneously.

    Key implications for developers:

    • Non-deterministic ordering: Do not rely on hooks running in a specific sequence.
    • Isolation: Hooks cannot see each other's output. Design every hook to be self-contained.
    • No shared state: Do not attempt to share state between different hooks.
    • Conflicting decisions: If multiple hooks attempt to make conflicting decisions (e.g., one allows and one denies), the behavior is undefined (often 'last write wins').

  12. Understand Gemini CLI Hook Security and Risks

    main

    Hooks introduce several security considerations based on their scope. The risk level increases as you move from system-level to project-level hooks.

    Threat Model (Safest to Riskiest):

    1. System-level hooks: Controlled by administrators.
    2. User-level hooks: Configured by the local user.
    3. Extension hooks: Third-party packages.
    4. Project-level hooks: Potentially from untrusted repositories.

    Key Security Behaviors:

    • First Detection Warning: Gemini CLI warns you when new project-level hooks are detected.
    • Command Identity: If a hook's command changes (e.g., via a git pull), the CLI treats it as a new, untrusted hook.
    • Mitigations: Always use timeout to prevent infinite loops, validate all inputs (as they may originate from LLMs), and avoid running hooks with root privileges.