Protokoll #1028

{
    "event": "PreToolUse",
    "tool_name": "Task",
    "tool_input": {
        "description": "Check hook blocking format",
        "prompt": "Wie muss ein PreToolUse Hook in Claude Code formatiert sein, um einen Befehl zu BLOCKIEREN? Was muss das Script ausgeben (JSON-Format, Exit-Code)?",
        "subagent_type": "claude-code-guide"
    }
}

{
    "tool_response": {
        "status": "completed",
        "prompt": "Wie muss ein PreToolUse Hook in Claude Code formatiert sein, um einen Befehl zu BLOCKIEREN? Was muss das Script ausgeben (JSON-Format, Exit-Code)?",
        "agentId": "a19a1ab",
        "content": [
            {
                "type": "text",
                "text": "Perfekt! Jetzt habe ich alle Informationen. Hier ist die detaillierte Antwort zur Formatierung eines blockierenden PreToolUse Hooks:\n\n## PreToolUse Hook Formatierung zum Blockieren eines Befehls\n\n### Hook-Struktur in settings.json\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"\/path\/to\/your\/block-script.py\",\n            \"timeout\": 5\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n### Script-Output zum Blockieren\n\nDu hast zwei Optionen:\n\n#### Option 1: Exit-Code 2 (Einfach)\n\nDas Script gibt **Exit-Code 2** zurück mit einer Fehlermeldung in `stderr`:\n\n```python\n#!\/usr\/bin\/env python3\nimport json\nimport sys\n\ntry:\n    input_data = json.load(sys.stdin)\nexcept json.JSONDecodeError:\n    sys.exit(1)\n\ntool_name = input_data.get(\"tool_name\", \"\")\ntool_input = input_data.get(\"tool_input\", {})\ncommand = tool_input.get(\"command\", \"\")\n\n# Beispiel: Blockiere direkte Datenbankzugriffe\nif \"mysql\" in command and \"--direct\" in command:\n    print(\"Direct database access not allowed\", file=sys.stderr)\n    sys.exit(2)  # Exit-Code 2 = BLOCKIERT\n```\n\n**Resultat:** Claude sieht die Fehlermeldung aus `stderr` und der Befehl wird nicht ausgeführt.\n\n#### Option 2: JSON Output mit Exit-Code 0 (Erweitert)\n\nDas Script gibt **Exit-Code 0** zurück mit strukturiertem JSON in `stdout`:\n\n```python\n#!\/usr\/bin\/env python3\nimport json\nimport sys\n\ntry:\n    input_data = json.load(sys.stdin)\nexcept json.JSONDecodeError:\n    sys.exit(1)\n\ntool_name = input_data.get(\"tool_name\", \"\")\ntool_input = input_data.get(\"tool_input\", {})\ncommand = tool_input.get(\"command\", \"\")\n\n# Blockiere den Befehl mit JSON-Output\nif \"rm -rf\" in command:\n    output = {\n        \"hookSpecificOutput\": {\n            \"hookEventName\": \"PreToolUse\",\n            \"permissionDecision\": \"deny\",\n            \"permissionDecisionReason\": \"Destructive commands (rm -rf) are not allowed for safety reasons\"\n        }\n    }\n    print(json.dumps(output))\n    sys.exit(0)  # Exit-Code 0 mit JSON!\n```\n\n### JSON-Format Detail\n\nDas JSON-Output bei PreToolUse blockiert mit diesen Feldern:\n\n```json\n{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"PreToolUse\",\n    \"permissionDecision\": \"deny\",\n    \"permissionDecisionReason\": \"Beschreibung warum blockiert\"\n  }\n}\n```\n\nMögliche `permissionDecision` Werte:\n- **`\"deny\"`** - Blockiert den Befehl\n- **`\"allow\"`** - Erlaubt automatisch (kann mit `updatedInput` modifiziert werden)\n- **`\"ask\"`** - Fragt den User\n\n### Praktisches Beispiel aus deinem Setup\n\nIn deiner `settings.json` hast du bereits blockierende Hooks:\n\n```json\n{\n  \"matcher\": \"Bash\",\n  \"hooks\": [\n    {\n      \"type\": \"command\",\n      \"command\": \"\/opt\/scripts\/hooks\/block_direct_db.py\"\n    },\n    {\n      \"type\": \"command\",\n      \"command\": \"\/opt\/scripts\/hooks\/block_direct_task_db.py\"\n    }\n  ]\n}\n```\n\nDiese Scripts sollten entweder:\n1. **Exit-Code 2 + stderr** zurückgeben wenn Befehl blockiert wird\n2. **Exit-Code 0 + JSON** mit `\"permissionDecision\": \"deny\"` ausgeben\n\n### Zusammenfassung\n\n| Aspekt | Wert |\n|--------|------|\n| **Blockieren via Exit-Code** | `exit 2` |\n| **Blockieren via JSON** | `exit 0` mit `\"permissionDecision\": \"deny\"` |\n| **Fehlermeldung Location** | `stderr` (Exit-Code 2) oder `permissionDecisionReason` (JSON) |\n| **Hook Event** | `PreToolUse` |\n| **Matcher** | Tool-Name z.B. `\"Bash\"`, `\"Edit\\|Write\"` oder `\"mcp__.*\"` |\n| **Timeout Standard** | 60 Sekunden (kann mit `\"timeout\"` überschrieben werden) |\n\nDie JSON-Variante ist flexibler, da Claude die `permissionDecisionReason` sieht und besser reagieren kann. Exit-Code 2 ist schneller und einfacher zu implementieren."
            }
        ],
        "totalDurationMs": 17763,
        "totalTokens": "[REDACTED]",
        "totalToolUseCount": 2,
        "usage": {
            "input_tokens": "[REDACTED]",
            "cache_creation_input_tokens": "[REDACTED]",
            "cache_read_input_tokens": "[REDACTED]",
            "cache_creation": {
                "ephemeral_5m_input_tokens": "[REDACTED]",
                "ephemeral_1h_input_tokens": "[REDACTED]"
            },
            "output_tokens": "[REDACTED]",
            "service_tier": "standard"
        }
    }
}