@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.1

package/extensions/plugin-dev/skills/hook-development/references/hook-input-schemas.md

@@ -0,0 +1,145 @@
+# Hook Input Schemas
+
+Comprehensive reference for all hook input schemas. Every hook receives JSON via stdin containing common fields plus event-specific fields.
+
+## Common Fields (All Hooks)
+
+Every hook receives these fields:
+
+| Field             | Type   | Description                    |
+| ----------------- | ------ | ------------------------------ |
+| `session_id`      | string | Unique session identifier      |
+| `transcript_path` | string | Path to conversation JSON      |
+| `cwd`             | string | Current working directory      |
+| `permission_mode` | string | Current permission mode        |
+| `hook_event_name` | string | Event that triggered this hook |
+
+## Event-Specific Input Fields
+
+### PreToolUse / PostToolUse / PostToolUseFailure / PermissionRequest
+
+| Field                    | Type    | Events             | Description                                   |
+| ------------------------ | ------- | ------------------ | --------------------------------------------- |
+| `tool_name`              | string  | All four           | Name of the tool                              |
+| `tool_input`             | object  | All four           | Arguments sent to the tool (see tool schemas) |
+| `tool_result`            | string  | PostToolUse        | Tool execution result                         |
+| `tool_use_id`            | string  | PostToolUse        | Unique tool use identifier                    |
+| `error`                  | string  | PostToolUseFailure | Error message from the failed tool            |
+| `is_interrupt`           | boolean | PostToolUseFailure | Whether failure was caused by user interrupt  |
+| `permission_suggestions` | array   | PermissionRequest  | Suggested permission decisions                |
+
+### UserPromptSubmit
+
+| Field    | Type   | Description                    |
+| -------- | ------ | ------------------------------ |
+| `prompt` | string | The user-submitted prompt text |
+
+### Stop / SubagentStop
+
+| Field                   | Type    | Events       | Description                                     |
+| ----------------------- | ------- | ------------ | ----------------------------------------------- |
+| `stop_hook_active`      | boolean | Both         | Whether hook is already continuing (loop guard) |
+| `agent_id`              | string  | SubagentStop | Unique subagent identifier                      |
+| `agent_type`            | string  | SubagentStop | Agent name                                      |
+| `agent_transcript_path` | string  | SubagentStop | Path to subagent transcript                     |
+
+### SubagentStart
+
+| Field        | Type   | Description                |
+| ------------ | ------ | -------------------------- |
+| `agent_id`   | string | Unique subagent identifier |
+| `agent_type` | string | Agent name                 |
+
+### SessionStart
+
+| Field        | Type   | Description                                      |
+| ------------ | ------ | ------------------------------------------------ |
+| `source`     | string | Matcher: `startup`, `resume`, `clear`, `compact` |
+| `model`      | string | Model identifier                                 |
+| `agent_type` | string | If running as an agent (optional)                |
+
+### SessionEnd
+
+| Field    | Type   | Description                                                                            |
+| -------- | ------ | -------------------------------------------------------------------------------------- |
+| `source` | string | Values: `clear`, `logout`, `prompt_input_exit`, `bypass_permissions_disabled`, `other` |
+
+### PreCompact
+
+| Field                 | Type   | Description                                |
+| --------------------- | ------ | ------------------------------------------ |
+| `trigger`             | string | `manual` or `auto`                         |
+| `custom_instructions` | string | User instructions (manual) or empty (auto) |
+
+### Notification
+
+| Field               | Type   | Description                                                              |
+| ------------------- | ------ | ------------------------------------------------------------------------ |
+| `message`           | string | Notification text                                                        |
+| `title`             | string | Notification title (optional)                                            |
+| `notification_type` | string | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog` |
+
+### TeammateIdle
+
+| Field           | Type   | Description   |
+| --------------- | ------ | ------------- |
+| `teammate_name` | string | Teammate name |
+| `team_name`     | string | Team name     |
+
+### TaskCompleted
+
+| Field              | Type   | Description                 |
+| ------------------ | ------ | --------------------------- |
+| `task_id`          | string | Task identifier             |
+| `task_subject`     | string | Task subject line           |
+| `task_description` | string | Task description (optional) |
+| `teammate_name`    | string | Teammate name (optional)    |
+| `team_name`        | string | Team name (optional)        |
+
+## Tool Input Schemas (for PreToolUse/PostToolUse)
+
+The `tool_input` object varies by tool. Common tool schemas:
+
+| Tool         | `tool_input` Fields                                                                                                                                                   |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Bash         | `command` (string), `description` (string, optional), `timeout` (number, optional), `run_in_background` (boolean, optional)                                           |
+| Write        | `file_path` (string), `content` (string)                                                                                                                              |
+| Edit         | `file_path` (string), `old_string` (string), `new_string` (string), `replace_all` (boolean, optional)                                                                 |
+| Read         | `file_path` (string), `offset` (number, optional), `limit` (number, optional)                                                                                         |
+| Glob         | `pattern` (string), `path` (string, optional)                                                                                                                         |
+| Grep         | `pattern` (string), `path` (string, optional), `glob` (string, optional), `output_mode` (string, optional), `-i` (boolean, optional), `multiline` (boolean, optional) |
+| WebFetch     | `url` (string), `prompt` (string)                                                                                                                                     |
+| WebSearch    | `query` (string), `allowed_domains` (array, optional), `blocked_domains` (array, optional)                                                                            |
+| Task         | `prompt` (string), `description` (string), `subagent_type` (string), `model` (string, optional)                                                                       |
+| Skill        | `skill` (string), `args` (string, optional)                                                                                                                           |
+| NotebookEdit | `notebook_path` (string), `new_source` (string), `cell_type` (string, optional), `edit_mode` (string, optional)                                                       |
+
+## Practical Example
+
+Extracting fields in a bash hook script using `jq`:
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+# Read full input from stdin
+input=$(cat)
+
+# Extract common fields
+session_id=$(echo "$input" | jq -r '.session_id')
+hook_event=$(echo "$input" | jq -r '.hook_event_name')
+
+# Extract tool-specific fields (PreToolUse/PostToolUse)
+tool_name=$(echo "$input" | jq -r '.tool_name // empty')
+file_path=$(echo "$input" | jq -r '.tool_input.file_path // empty')
+command=$(echo "$input" | jq -r '.tool_input.command // empty')
+
+# Example: block writes to sensitive paths
+if [[ "$tool_name" == "Write" && "$file_path" == *".env"* ]]; then
+  echo '{"decision": "deny", "reason": "Cannot write to .env files"}' >&2
+  exit 2
+fi
+
+# Allow by default
+exit 0
+```

package/extensions/plugin-dev/skills/hook-development/references/migration.md

@@ -0,0 +1,392 @@
+# Migrating from Basic to Advanced Hooks
+
+This guide shows how to migrate from basic command hooks to advanced prompt-based hooks for better maintainability and flexibility.
+
+## Why Migrate?
+
+Prompt-based hooks offer several advantages:
+
+- **Natural language reasoning**: LLM understands context and intent
+- **Better edge case handling**: Adapts to unexpected scenarios
+- **No bash scripting required**: Simpler to write and maintain
+- **More flexible validation**: Can handle complex logic without coding
+
+## Migration Example: Bash Command Validation
+
+### Before (Basic Command Hook)
+
+**Configuration:**
+
+```json
+{
+  "PreToolUse": [
+    {
+      "matcher": "Bash",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash validate-bash.sh"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Script (validate-bash.sh):**
+
+```bash
+#!/bin/bash
+input=$(cat)
+command=$(echo "$input" | jq -r '.tool_input.command')
+
+# Hard-coded validation logic
+if [[ "$command" == *"rm -rf"* ]]; then
+  echo "Dangerous command detected" >&2
+  exit 2
+fi
+```
+
+**Problems:**
+
+- Only checks for exact "rm -rf" pattern
+- Doesn't catch variations like `rm -fr` or `rm -r -f`
+- Misses other dangerous commands (`dd`, `mkfs`, etc.)
+- No context awareness
+- Requires bash scripting knowledge
+
+### After (Advanced Prompt Hook)
+
+**Configuration:**
+
+```json
+{
+  "PreToolUse": [
+    {
+      "matcher": "Bash",
+      "hooks": [
+        {
+          "type": "prompt",
+          "prompt": "Command: $TOOL_INPUT.command. Analyze for: 1) Destructive operations (rm -rf, dd, mkfs, etc) 2) Privilege escalation (sudo) 3) Network operations without user consent. Return 'approve' or 'deny' with explanation.",
+          "timeout": 15
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Benefits:**
+
+- Catches all variations and patterns
+- Understands intent, not just literal strings
+- No script file needed
+- Easy to extend with new criteria
+- Context-aware decisions
+- Natural language explanation in denial
+
+## Migration Example: File Write Validation
+
+### Before (Basic Command Hook)
+
+**Configuration:**
+
+```json
+{
+  "PreToolUse": [
+    {
+      "matcher": "Write",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash validate-write.sh"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Script (validate-write.sh):**
+
+```bash
+#!/bin/bash
+input=$(cat)
+file_path=$(echo "$input" | jq -r '.tool_input.file_path')
+
+# Check for path traversal
+# NOTE: This basic check catches literal ".." but has limitations:
+# - Does not detect URL-encoded traversal (%2e%2e)
+# - Cannot detect symlink-based traversal where resolved path escapes bounds
+# - Shell expansion could bypass in some contexts
+# For production hooks, consider using:
+#   resolved=$(realpath -m "$file_path" 2>/dev/null || echo "$file_path")
+# and comparing against an allowed directory prefix
+if [[ "$file_path" == *".."* ]]; then
+  echo '{"decision": "deny", "reason": "Path traversal detected"}' >&2
+  exit 2
+fi
+
+# Check for system paths
+if [[ "$file_path" == "/etc/"* ]] || [[ "$file_path" == "/sys/"* ]]; then
+  echo '{"decision": "deny", "reason": "System file"}' >&2
+  exit 2
+fi
+```
+
+**Problems:**
+
+- Hard-coded path patterns
+- Doesn't understand symlinks
+- Missing edge cases (e.g., `/etc` vs `/etc/`)
+- No consideration of file content
+
+### After (Advanced Prompt Hook)
+
+**Configuration:**
+
+```json
+{
+  "PreToolUse": [
+    {
+      "matcher": "Write|Edit",
+      "hooks": [
+        {
+          "type": "prompt",
+          "prompt": "File path: $TOOL_INPUT.file_path. Content preview: $TOOL_INPUT.content (first 200 chars). Verify: 1) Not system directories (/etc, /sys, /usr) 2) Not credentials (.env, tokens, secrets) 3) No path traversal 4) Content doesn't expose secrets. Return 'approve' or 'deny'."
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Benefits:**
+
+- Context-aware (considers content too)
+- Handles symlinks and edge cases
+- Natural understanding of "system directories"
+- Can detect secrets in content
+- Easy to extend criteria
+
+## When to Keep Command Hooks
+
+Command hooks still have their place:
+
+### 1. Deterministic Performance Checks
+
+```bash
+#!/bin/bash
+# Check file size quickly
+file_path=$(echo "$input" | jq -r '.tool_input.file_path')
+size=$(stat -f%z "$file_path" 2>/dev/null || stat -c%s "$file_path" 2>/dev/null)
+
+if [ "$size" -gt 10000000 ]; then
+  echo '{"decision": "deny", "reason": "File too large"}' >&2
+  exit 2
+fi
+```
+
+**Use command hooks when:** Validation is purely mathematical or deterministic.
+
+### 2. External Tool Integration
+
+```bash
+#!/bin/bash
+# Run security scanner
+file_path=$(echo "$input" | jq -r '.tool_input.file_path')
+scan_result=$(security-scanner "$file_path")
+
+if [ "$?" -ne 0 ]; then
+  echo "Security scan failed: $scan_result" >&2
+  exit 2
+fi
+```
+
+**Use command hooks when:** Integrating with external tools that provide yes/no answers.
+
+### 3. Very Fast Checks (< 50ms)
+
+```bash
+#!/bin/bash
+# Quick regex check
+command=$(echo "$input" | jq -r '.tool_input.command')
+
+if [[ "$command" =~ ^(ls|pwd|echo)$ ]]; then
+  exit 0  # Safe commands
+fi
+```
+
+**Use command hooks when:** Performance is critical and logic is simple.
+
+## Hybrid Approach
+
+Combine both for multi-stage validation:
+
+```json
+{
+  "PreToolUse": [
+    {
+      "matcher": "Bash",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/quick-check.sh",
+          "timeout": 5
+        },
+        {
+          "type": "prompt",
+          "prompt": "Deep analysis of bash command: $TOOL_INPUT",
+          "timeout": 15
+        }
+      ]
+    }
+  ]
+}
+```
+
+The command hook does fast deterministic checks, while the prompt hook handles complex reasoning.
+
+## Migration Checklist
+
+When migrating hooks:
+
+- [ ] Identify the validation logic in the command hook
+- [ ] Convert hard-coded patterns to natural language criteria
+- [ ] Test with edge cases the old hook missed
+- [ ] Verify LLM understands the intent
+- [ ] Set appropriate timeout (usually 15-30s for prompt hooks)
+- [ ] Document the new hook in README
+- [ ] Remove or archive old script files
+
+## Migration Tips
+
+1. **Start with one hook**: Don't migrate everything at once
+2. **Test thoroughly**: Verify prompt hook catches what command hook caught
+3. **Look for improvements**: Use migration as opportunity to enhance validation
+4. **Keep scripts for reference**: Archive old scripts in case you need to reference the logic
+5. **Document reasoning**: Explain why prompt hook is better in README
+
+## Complete Migration Example
+
+### Original Plugin Structure
+
+```
+my-plugin/
+├── .claude-plugin/plugin.json
+├── hooks/hooks.json
+└── scripts/
+    ├── validate-bash.sh
+    ├── validate-write.sh
+    └── check-tests.sh
+```
+
+### After Migration
+
+```
+my-plugin/
+├── .claude-plugin/plugin.json
+├── hooks/hooks.json      # Now uses prompt hooks
+└── scripts/              # Archive or delete
+    └── archive/
+        ├── validate-bash.sh
+        ├── validate-write.sh
+        └── check-tests.sh
+```
+
+### Updated hooks.json
+
+```json
+{
+  "PreToolUse": [
+    {
+      "matcher": "Bash",
+      "hooks": [
+        {
+          "type": "prompt",
+          "prompt": "Validate bash command safety: destructive ops, privilege escalation, network access"
+        }
+      ]
+    },
+    {
+      "matcher": "Write|Edit",
+      "hooks": [
+        {
+          "type": "prompt",
+          "prompt": "Validate file write safety: system paths, credentials, path traversal, content secrets"
+        }
+      ]
+    }
+  ],
+  "Stop": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "prompt",
+          "prompt": "Verify tests were run if code was modified"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Result:** Simpler, more maintainable, more powerful.
+
+## Common Migration Patterns
+
+### Pattern: String Contains → Natural Language
+
+**Before:**
+
+```bash
+if [[ "$command" == *"sudo"* ]]; then
+  echo "Privilege escalation" >&2
+  exit 2
+fi
+```
+
+**After:**
+
+```
+"Check for privilege escalation (sudo, su, etc)"
+```
+
+### Pattern: Regex → Intent
+
+**Before:**
+
+```bash
+if [[ "$file" =~ \.(env|secret|key|token)$ ]]; then
+  echo "Credential file" >&2
+  exit 2
+fi
+```
+
+**After:**
+
+```
+"Verify not writing to credential files (.env, secrets, keys, tokens)"
+```
+
+### Pattern: Multiple Conditions → Criteria List
+
+**Before:**
+
+```bash
+if [ condition1 ] || [ condition2 ] || [ condition3 ]; then
+  echo "Invalid" >&2
+  exit 2
+fi
+```
+
+**After:**
+
+```
+"Check: 1) condition1 2) condition2 3) condition3. Deny if any fail."
+```
+
+## Conclusion
+
+Migrating to prompt-based hooks makes plugins more maintainable, flexible, and powerful. Reserve command hooks for deterministic checks and external tool integration.