Support Cursor preToolUse hook

The `beforeShellExecution` hook is a more natural place for Dippy but
it's currently broken because Cursor won't honor "allow" responses it
always runs it's own approval prompt after the hook unless the hook
denies the request.

I updated the docs too to call out the issue but this appears to now
work the same as claude

Author: Nick Davies

README.md

@@ -88,18 +88,24 @@ Add to `~/.cursor/hooks.json` (global) or `.cursor/hooks.json` in your project r
 {
   "version": 1,
   "hooks": {
-    "beforeShellExecution": [
-      { "command": "dippy" }
+    "preToolUse": [
+      { "matcher": "Shell", "command": "dippy" }
     ]
   }
 }
 ```
 
+The `matcher` ensures Dippy only runs for shell commands, not every tool invocation.
+
 Dippy auto-detects Cursor's input format, so no extra flags are needed. If you prefer to be explicit, use `dippy --cursor` or set `DIPPY_CURSOR=1`.
 
 Logs go to `~/.cursor/hook-approvals.log`.
 
-> **Note:** Cursor has a known bug where only the first hook in an array runs. If you have other `beforeShellExecution` hooks, Dippy must be listed first.
+> **Note:** Cursor has a known bug where only the first hook in an array runs. If you have other hooks of the same type, Dippy must be listed first.
+
+> **Note:** Cursor's `beforeShellExecution` hook has a known bug where `allow` responses are ignored — only `deny` works correctly. Use `preToolUse` instead, which handles all tool types and respects allow/deny/ask.
+
+> **Note:** Cursor's sandbox mode bypasses hook permission decisions. Commands that run in the sandbox are auto-approved regardless of what the hook returns. Only unsandboxed commands (those requiring `required_permissions`) respect `ask` and `deny` responses.
 
 If you installed manually, use the full path instead: `/path/to/Dippy/bin/dippy-hook`
 

src/dippy/dippy.py

@@ -53,10 +53,14 @@ def _detect_mode_from_flags() -> str | None:
 
 def _detect_mode_from_input(input_data: dict) -> str:
     """Auto-detect mode from input JSON structure."""
-    # Cursor: {"command": "...", "cwd": "..."}
+    # Cursor beforeShellExecution: {"command": "...", "cwd": "..."}
     if "command" in input_data and "tool_name" not in input_data:
         return "cursor"
 
+    # Cursor preToolUse: has cursor_version field
+    if "cursor_version" in input_data:
+        return "cursor"
+
     # Claude/Gemini: {"tool_name": "...", "tool_input": {...}}
     tool_name = input_data.get("tool_name", "")
 
@@ -259,6 +263,7 @@ def handle_mcp_post_tool_use(tool_name: str, config: Config) -> None:
 SHELL_TOOL_NAMES = frozenset(
     {
         "Bash",  # Claude Code
+        "Shell",  # Cursor preToolUse
         "shell",  # Gemini CLI
         "run_shell",  # Gemini CLI alternate
         "run_shell_command",  # Gemini CLI official name
@@ -340,12 +345,20 @@ def main():
         hook_event = input_data.get("hook_event_name", "PreToolUse")
 
         # Extract command based on mode
-        # Cursor: {"command": "...", "cwd": "..."}
+        # Cursor beforeShellExecution: {"command": "...", "cwd": "..."}
+        # Cursor preToolUse: {"tool_name": "Shell", "tool_input": {"command": "..."}}
         # Claude/Gemini: {"tool_name": "...", "tool_input": {"command": "..."}}
         if MODE == "cursor":
-            # Cursor sends command directly (beforeShellExecution hook)
-            command = input_data.get("command", "")
-            tool_name = None
+            # beforeShellExecution hook: command is top-level
+            # preToolUse hook (delegated via claude-approve): command is in tool_input
+            tool_name = input_data.get("tool_name")
+            if tool_name is not None:
+                if tool_name not in SHELL_TOOL_NAMES:
+                    print(json.dumps({}))
+                    return
+                command = input_data.get("tool_input", {}).get("command", "")
+            else:
+                command = input_data.get("command", "")
         else:
             # Claude Code and Gemini CLI use tool_name/tool_input format
             tool_name = input_data.get("tool_name", "")

tests/test_entrypoint.py

@@ -129,6 +129,52 @@ def test_non_bash_tool_passthrough(self):
         assert output == {}
 
 
+class TestCursorPreToolUse:
+    """Tests for Cursor preToolUse hook format."""
+
+    def test_cursor_pretooluse_shell_allowed(self):
+        """Cursor preToolUse with Shell tool and safe command returns allow."""
+        input_data = {
+            "tool_name": "Shell",
+            "tool_input": {"command": "git status", "cwd": ""},
+            "hook_event_name": "preToolUse",
+            "cursor_version": "2.6.18",
+            "workspace_roots": ["/tmp"],
+        }
+        result = run_hook(input_data)
+        assert result.returncode == 0
+        output = json.loads(result.stdout)
+        assert output.get("permission") == "allow"
+
+    def test_cursor_pretooluse_shell_dangerous(self):
+        """Cursor preToolUse with Shell tool and dangerous command returns ask."""
+        input_data = {
+            "tool_name": "Shell",
+            "tool_input": {"command": "rm -rf /", "cwd": ""},
+            "hook_event_name": "preToolUse",
+            "cursor_version": "2.6.18",
+            "workspace_roots": ["/tmp"],
+        }
+        result = run_hook(input_data)
+        assert result.returncode == 0
+        output = json.loads(result.stdout)
+        assert output.get("permission") == "ask"
+
+    def test_cursor_pretooluse_non_shell_passthrough(self):
+        """Cursor preToolUse with non-Shell tool returns empty (passthrough)."""
+        input_data = {
+            "tool_name": "Read",
+            "tool_input": {"path": "/etc/passwd"},
+            "hook_event_name": "preToolUse",
+            "cursor_version": "2.6.18",
+            "workspace_roots": ["/tmp"],
+        }
+        result = run_hook(input_data)
+        assert result.returncode == 0
+        output = json.loads(result.stdout)
+        assert output == {}
+
+
 class TestErrorHandling:
     """Test graceful handling of bad input."""
 

tests/test_modes.py

@@ -245,11 +245,45 @@ def test_auto_detect_cursor_from_input():
     """Test auto-detection of Cursor mode from input structure."""
     from dippy.dippy import _detect_mode_from_input
 
-    # Cursor sends command directly without tool_name
+    # Cursor beforeShellExecution: command directly without tool_name
     input_data = {"command": "ls", "cwd": "/home/user"}
     assert _detect_mode_from_input(input_data) == "cursor"
 
 
+def test_auto_detect_cursor_pretooluse_from_input():
+    """Test auto-detection of Cursor mode from preToolUse input structure."""
+    from dippy.dippy import _detect_mode_from_input
+
+    # Cursor preToolUse: has cursor_version field
+    input_data = {
+        "tool_name": "Shell",
+        "tool_input": {"command": "ls", "cwd": ""},
+        "hook_event_name": "preToolUse",
+        "cursor_version": "2.6.18",
+    }
+    assert _detect_mode_from_input(input_data) == "cursor"
+
+
+def test_auto_detect_cursor_pretooluse_non_shell_tool():
+    """Test auto-detection of Cursor mode for non-shell preToolUse tools."""
+    from dippy.dippy import _detect_mode_from_input
+
+    input_data = {
+        "tool_name": "Read",
+        "tool_input": {"path": "/some/file"},
+        "hook_event_name": "preToolUse",
+        "cursor_version": "2.6.18",
+    }
+    assert _detect_mode_from_input(input_data) == "cursor"
+
+
+def test_shell_tool_names_includes_cursor():
+    """Test that SHELL_TOOL_NAMES includes Cursor's Shell tool name."""
+    from dippy.dippy import SHELL_TOOL_NAMES
+
+    assert "Shell" in SHELL_TOOL_NAMES
+
+
 def test_no_flag_defaults_to_auto_detect(monkeypatch):
     """Test that no flag means auto-detection will be used."""
     monkeypatch.setattr("sys.argv", ["dippy"])