Hook

# Look for existing hooks.json in plugin context
cat <target-plugin>/hooks/hooks.json 2>/dev/null

• If exists → switch to Update mode (jump to "Update Workflow" section at the end)
• If not → continue with Create mode (proceed to Step 2)

Step 2: Analyze the Description

From the description, determine:

Event Type

Match the description to the most appropriate hook event:

If the intent is ambiguous, ask the user to clarify.

Hook Type

Matcher Pattern

• For PreToolUse/PostToolUse: regex matching tool names (e.g., Bash, Read\|Write\|Edit, Bash\(rm\|mv\))
• For Notification: event type string
• For SessionStart: trigger type
• For other events: usually not needed

Script Language (for command type)

• Node.js if: complex JSON parsing, multiple conditions, file system operations
• Bash if: simple checks, calling system commands (afplay, osascript, notify-send)

Step 2.5: Interactive Clarification

Review what was determined in Step 2. If the description is precise enough to resolve all decisions, skip this step entirely.

Otherwise, use AskUserQuestion to ask only about decisions that remain ambiguous:

• "Which event should trigger this hook?" — if the description could match multiple events (e.g., PreToolUse vs PostToolUse)
• "What type of hook?" (command/http/prompt/agent) — if not obvious from the description
• "Which tool(s) should the matcher target?" — if PreToolUse event and the tool scope is unclear
• "Should the script be Node.js or Bash?" — for command type when the complexity is borderline

Rules:

• Ask at most 2-3 questions in a single prompt. Do not bombard the user.
• If the description already implies clear answers, do not ask. Assume defaults.
• Merge answers back into the analysis from Step 2 before proceeding.

Step 3: Detect Target Path

Resolution logic:

1. If CWD matches */plugins/<plugin-name>/* → write to plugin's hooks/ directory
2. If CWD contains .claude-plugin/marketplace.json → ask which plugin to target
3. Otherwise → the hook goes into project settings (.claude/settings.json or .claude/settings.local.json)

For plugin context: generate hooks/hooks.json + scripts/<script-name>.js|sh For standalone context: generate the hook config to be added to settings.json

Step 4: Check for Existing Hooks

# Check for existing hooks.json in plugin context
cat <target-plugin>/hooks/hooks.json 2>/dev/null

If hooks.json already exists:

• Read the existing file
• Append the new hook entry to the appropriate event array
• Do NOT overwrite existing hooks
• If the same event+matcher combination already exists, warn the user

If no hooks.json exists:

• Create a new one from the template

Step 5: Generate the Hook

For command type hooks:

1. Generate/update hooks.json:

   • Use the hook-command.json template as base
   • Fill in: description, event, matcher, script path, timeout
   • Default timeout: 5000ms for quick checks, 10000ms for network calls, 30000ms for complex operations

2. Generate the script:

   • Create scripts/<descriptive-name>.js or scripts/<descriptive-name>.sh
   • Use the appropriate template (hook-script.js or hook-script.sh)
   • Write the ACTUAL logic, not placeholder code
   • Include proper error handling
   • For blocking hooks: write clear stderr messages explaining WHY the action was blocked
   • For notification hooks: handle cross-platform (macOS/Linux/Windows)

For http type hooks:

Generate hooks.json with:

{
  "type": "http",
  "url": "{{URL}}",
  "headers": { "Content-Type": "application/json" },
  "timeout": 10000
}

For prompt type hooks:

Generate hooks.json with:

{
  "type": "prompt",
  "prompt": "{{EVALUATION_PROMPT}}"
}

For agent type hooks:

Generate hooks.json with:

{
  "type": "agent",
  "agent": "{{AGENT_NAME}}",
  "prompt": "{{VERIFICATION_PROMPT}}"
}

Step 6: Cross-Platform Considerations

For scripts that use system commands:

Include platform detection in scripts:

case "$(uname -s)" in
  Darwin*) # macOS ;;
  Linux*)  # Linux ;;
  MINGW*|MSYS*|CYGWIN*) # Windows ;;
esac

Update Workflow (Update Mode)

When Step 1.5 detected an existing hooks.json:

U1: Read Existing Hooks

cat <target-plugin>/hooks/hooks.json

Parse all existing hook entries grouped by event type.

U2: Show Current Hooks

Display the existing hooks to the user:

Current hooks in <plugin-name>:
  1. [PreToolUse] matcher: "Bash" → scripts/block-dangerous.sh
  2. [Stop] → scripts/notify-done.js
  ...

Use AskUserQuestion to ask:

• "Here are the existing hooks. Which one do you want to modify? Or should I add a new hook?"

U3: Propose Changes

Based on the user's answer:

For modifications:

• Show current hook config and script logic
• Propose specific changes via AskUserQuestion:
  • "Here is the current script logic. What should change?"
  • Show before/after for the hooks.json entry

For additions:

• Proceed with normal creation flow (Steps 2-5) but append to existing hooks.json instead of creating new

U4: Apply Approved Changes

• Use Edit (not Write) to modify hooks.json entries
• For script changes: use Edit to update only the affected sections
• Preserve all hooks and scripts the user did not ask to change

U5: Post-Update Summary

Display:

Hook updated: <event-type> [<matcher>]
Location: <path-to-hooks.json>
Script: <path-to-script> (if modified)
Changes: <summary of what changed>

Step 7: Post-Generation Summary

Display:

Hook created:
  Event: <event-type>
  Matcher: <matcher-pattern>
  Type: <hook-type>
  Location: <path-to-hooks.json>
  Script: <path-to-script> (if applicable)

Exit codes: 0 = allow | 2 = block

Tip: Run /factory:audit <hooks.json-path> to validate.