hooks-worker

name	hooks-worker
description	Hook system optimization — async conversion, consolidation, deduplication, new hook events

Hooks Worker

NOTE: Startup and cleanup are handled by worker-base. This skill defines the WORK PROCEDURE.

When to Use This Skill

Features that modify .claude/settings.json hook registrations, create new hook scripts, consolidate existing hooks, or add new hook event categories.

Work Procedure

1. Read the feature description carefully. Understand exactly which hooks to modify, what safety classification to respect, and what the expected settings.json structure should be.

2. Baseline snapshot. Before ANY changes, read .claude/settings.json and record:

   • Total hook count per event category
   • Which hooks are async vs sync
   • Which hooks have timeout_ms
   • The exact matcher strings for hooks being modified

3. Write tests first (red). Create test file at tests/hooks/<descriptive-name>.test.cjs. Tests should verify:

   • settings.json structure (JSON validity, event categories present)
   • Hook classification (async/sync status per hook)
   • Matcher coverage (all tool names in combined matchers)
   • For new hooks: input/output behavior, error handling, fail-open behavior
   • For consolidated hooks: error isolation, sub-function invocation Run tests — they should FAIL (red).

4. Implement changes.

   • For settings.json edits: Read the full file, make targeted edits, write back. ALWAYS validate JSON after writing.
   • For new hook scripts: Follow established patterns from existing hooks. Use 'use strict', project-root.cjs, safeParseJSON, formatResult(). Security hooks exit 2 to block; advisory hooks exit 0.
   • For consolidated hooks: Import sub-modules with try/catch per call. Always exit 0. Respect kill-switch env vars.
   • NEVER make a security hook async. NEVER remove a security hook's ability to block.

5. Run tests (green). All tests pass. Fix any failures.

6. Validate settings.json.

   node -e "JSON.parse(require('fs').readFileSync('.claude/settings.json','utf8'))"
   

7. Run lint and format.

   pnpm lint
   pnpm format:check
   

8. Manual verification. For new hooks, run them manually with sample input to verify behavior. For settings.json changes, diff against baseline to confirm only intended changes were made.

Example Handoff

{
  "salientSummary": "Converted 22 advisory hooks to async:true in settings.json. Zero security hooks affected. Added timeout_ms to 40 hooks that were missing it. settings.json valid JSON with all 7 event categories preserved. Created tests/hooks/hook-async-classification.test.cjs (15 tests).",
  "whatWasImplemented": "Parsed settings.json, classified each hook by reading its source (exit 2 = blocking/sync, exit 0 = advisory/async candidate). Added async:true to 22 advisory hooks across UserPromptSubmit, PostToolUse, PostToolUseFailure. Left all 18 security/blocking hooks as sync. Added timeout_ms to 40 hooks: 5000ms for simple advisory, 10000ms for monitoring, 15000ms for file-scanning, 30000ms for cleanup.",
  "whatWasLeftUndone": "",
  "verification": {
    "commandsRun": [
      {
        "command": "node --test tests/hooks/hook-async-classification.test.cjs",
        "exitCode": 0,
        "observation": "15 tests passing"
      },
      {
        "command": "node -e \"JSON.parse(require('fs').readFileSync('.claude/settings.json','utf8'))\"",
        "exitCode": 0,
        "observation": "Valid JSON"
      },
      {
        "command": "pnpm lint",
        "exitCode": 0,
        "observation": "0 errors"
      }
    ]
  },
  "tests": {
    "added": [
      {
        "file": "tests/hooks/hook-async-classification.test.cjs",
        "cases": [
          { "name": "advisory hooks have async:true", "verifies": "VAL-HO-003" },
          { "name": "security hooks do NOT have async:true", "verifies": "VAL-HO-002" },
          { "name": "all hooks have timeout_ms", "verifies": "VAL-HO-004" }
        ]
      }
    ]
  },
  "discoveredIssues": []
}

When to Return to Orchestrator

• A hook you need to modify doesn't exist at the expected path
• You're unsure whether a hook is security-critical or advisory
• Consolidation would require changing a hook's exit code behavior
• settings.json has an unexpected structure that doesn't match the baseline
• A hook depends on another hook's execution order and consolidation would break that dependency