create-hook

Files (1)

• SKILL.md

SKILL.md (first lines)

## Create/Modify Hook — Production-Grade Hook Engineering

All hooks are **fail-open** — timeout means silent pass. Quality = system stability.

> bash script based (no Python dependency).

---

## Step 1: Behavior Analysis — What to Block

### 1A: Explicit Request
User specifies the behavior to block → proceed to Step 2.

### 1B: Conversation Analysis
If the request is ambiguous, detect patterns from recent conversation:
- Behaviors the user corrected or reverted
- Repeated mistakes (same hook bypassed 2+ times)
- Frustration signals

Confirm detected patterns with user before proceeding.

---

## Step 2: Hook Design

### Event + Matcher Decision

| Event | Matcher | Purpose |
|-------|---------|---------|
| PreToolUse | Bash | Command blocking/warning |
| PreToolUse | Edit\|Write | File modification control |
| PreToolUse | Agent | Agent spawn control |
| PreToolUse | TeamCreate | Team creation control |
| PreToolUse | TaskUpdate | Task status change control |
| PostToolUse | Bash | Post-commit checks |
| PostToolUse | Edit\|Write | Post-modification audit |
| SubagentStop | (all) | Agent exit report verification |
| Stop | (all) | Session end checks |
| SessionStart | (all) | Session initialization |

### Action Type Decision

| Type | exit code | Behavior | Purpose |
|------|-----------|----------|---------|
| BLOCK | `exit 1` | Stop tool call | Rule violation blocking |
| HARD BLOCK | `exit 2` | Stop tool call | Severe violation blocking |
| WARNING | `exit 0` + stdout | Proceed with tool call | Warning only |
| PASS | `exit 0` (silent) | Proceed with tool call | Normal pass |

> **timeout exceeded = fail-open** — tool call proceeds. Hook is neutralized.

---

## Step 3: Code Writing

### Required Template

```bash
#!/usr/bin/env bash
# Hook: {name} — {one-line description}
# Trigger: {PreToolUse|PostToolUse|SubagentStop|Stop} -> {matcher}
# Action: {BLOCK|HARD BLOCK|WARNING|PASS}
# Created: {YYYY-MM-DD}

INPUT=$(cat)

# === PARSE ===
# Use printf '%s' (shell injection prevention — never echo "$VAR")
FIELD=$(printf '%s' "$INPUT" | jq -r '.tool_input.field // empty')

# === FAST EXIT ===
# Most calls are irrelevant → pass quickly
if [ -z "$FIELD" ]; then
  exit 0
fi

# === VALIDATE ===
# Validation logic...

# === BLOCK (4-field diagnostic message) ===
cat >&2 <<EOF
BLOCKED: {one-line summary}
HOOK: {filename}.sh
ATTEMPTED: {what was tried — tool, parameters, target}
REASON: {why blocked — specific rule/Standing Order violated}
FIX: {how to resolve — specific command or steps}
EOF
exit 1
```

### 4-Field Diagnostic Message (Required on BLOCK)

All BLOCK/HARD BLOCK messages must include:

| Field | Purpose | Example |
|-------|---------|---------|
| `BLOCKED:` | One-line summary | "C-Suite spawned without team" |
| `HOOK:` | Which hook | "layer3-gate.sh" |
| `ATTEMPTED:` | What was tried | "Agent(subagent_type=cto, team_name=none)" |
| `REASON:` | Why blocked | "Standing Order #1: All C-Suite must spawn in team" |
| `FIX:` | How to fix | "TeamCreate('exec-cto') then pass team_name" |

### Security Rules

```bash
# DO — use printf '%s'
ATYPE=$(printf '%s' "$INPUT" | jq -r '.tool_input.subagent_type // empty')

# DON'T — never use echo (injection vector)
# ATYPE=$(echo "$INPUT" | jq -r '.tool_input.subagent_type // empty')

# DO — quote all variables
if [ -f "$ROOT/.claude/agents/$AGENT.md" ]; then

# DON'T — never eval/exec external input
# eval "$USER_INPUT"
```

---

From tyjpark0317/enterprise-os, MIT.

More from tyjpark0317/enterprise-os