fix: harden example hook validation scripts against bypass attacks (#164)

## Summary

Hardens the example hook validation scripts to prevent security bypass
patterns that users might inadvertently copy when creating their own
hooks.

## Problem

Fixes #161

The example hook validation scripts in
`skills/hook-development/examples/` had security gaps:

1. **validate-bash.sh**: The "safe command" allowlist (ls, pwd, echo,
etc.) could be bypassed with command chaining:
   - `echo $(rm -rf /)` - command substitution
   - `ls; rm -rf /` - semicolon chaining  
   - `pwd && malicious` - AND chaining

2. **validate-write.sh**: The path traversal check only detected literal
`..` without documenting limitations like URL-encoding or symlink
traversal.

## Solution

### validate-bash.sh
Added command chaining detection **before** the safe command allowlist:
- Checks for `;`, `|`, `$(`, `` ` ``, `&&`, `||`
- Returns `"permissionDecision": "ask"` to require user review
- Added comment explaining this is the critical ordering

### validate-write.sh  
Added comprehensive documentation about limitations:
- Notes that literal `..` check doesn't catch URL-encoded or symlink
traversal
- Provides guidance for production hardening using `realpath`
- Suggests comparing against allowed directory prefixes

### Alternatives Considered

1. **More comprehensive bash validation** - Could add newline, null
byte, and shell-specific syntax detection. Decided against to keep
examples teachable rather than production-ready.

2. **Add realpath resolution to validate-write.sh** - Decided
documentation is more appropriate for an example script, as realpath
behavior varies across systems.

## Changes

-
`plugins/plugin-dev/skills/hook-development/examples/validate-bash.sh`:
Added command chaining detection block with explanatory comments
-
`plugins/plugin-dev/skills/hook-development/examples/validate-write.sh`:
Added documentation comments about path traversal limitations

## Testing

- [x] Verified semicolon chaining now caught: `echo '{"tool_input":
{"command": "echo; malicious"}}' | bash validate-bash.sh` → exit 2
- [x] Verified simple commands still pass: `echo '{"tool_input":
{"command": "echo hello"}}' | bash validate-bash.sh` → exit 0
- [x] shellcheck passes on both modified scripts
- [x] markdownlint passes on related documentation

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: sjnims

plugins/plugin-dev/skills/hook-development/examples/validate-bash.sh

@@ -16,7 +16,21 @@ if [ -z "$command" ]; then
   exit 0
 fi
 
+# SECURITY: Check for command chaining/injection patterns FIRST
+# These checks must run before the "safe command" allowlist to prevent bypasses
+# like: echo $(rm -rf /), ls; malicious, pwd && evil, whoami | exfil
+# Note: This is not exhaustive - production hooks should consider additional
+# patterns like newlines (\n), null bytes (\x00), and shell-specific syntax
+# shellcheck disable=SC2016 # Single quotes intentional - matching literal $( and ` characters
+if [[ "$command" == *";"* ]] || [[ "$command" == *"|"* ]] ||
+   [[ "$command" == *'$('* ]] || [[ "$command" == *'`'* ]] ||
+   [[ "$command" == *"&&"* ]] || [[ "$command" == *"||"* ]]; then
+  echo '{"hookSpecificOutput": {"permissionDecision": "ask"}, "systemMessage": "Command chaining detected - requires review"}' >&2
+  exit 2
+fi
+
 # Check for obviously safe commands (quick approval)
+# IMPORTANT: This check is only safe because chaining patterns are caught above
 if [[ "$command" =~ ^(ls|pwd|echo|date|whoami)(\s|$) ]]; then
   exit 0
 fi

plugins/plugin-dev/skills/hook-development/examples/validate-write.sh

@@ -17,6 +17,13 @@ if [ -z "$file_path" ]; then
 fi
 
 # 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
   jq -n --arg path "$file_path" \
     '{"hookSpecificOutput": {"permissionDecision": "deny"}, "systemMessage": "Path traversal detected in: \($path)"}' >&2

plugins/plugin-dev/skills/hook-development/references/migration.md

@@ -108,6 +108,13 @@ 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