Hooks System

The hooks system is the enforcement layer of dq-awesomeqa. Three scripts run automatically at specific coding-agent lifecycle events - you configure nothing.

---

Hook registry: hooks/hooks.json

{
  "hooks": [
    {
      "event": "UserPromptSubmit",
      "script": "hooks/sanitize-input.js"
    },
    {
      "event": "PreToolUse",
      "script": "hooks/qa-safety.js"
    },
    {
      "event": "*",
      "script": "hooks/audit-log.js"
    }
  ]
}

---

sanitize-input.js

Property	Value
Event	UserPromptSubmit
Language	Node.js
Exit 0	Allow
Exit 1	Soft warning (logged, not blocked)
Exit 2	Hard block (message dropped)

Scans the raw user prompt for prompt injection patterns before the coding agent processes it. Patterns include embedded instruction overrides, role-switching attempts, and commands disguised as question text.

---

audit-log.js

Property	Value
Event	* (all events)
Language	Node.js
Output	.claude/logs/session-<date>-<id>.jsonl

Appends one JSONL line per event. Each line contains:

{
  "ts": "2026-05-26T10:34:12.000Z",
  "event": "PreToolUse",
  "tool": "Write",
  "input": {
    "file_path": "qa-reports/api/api-test-plan.json"
  }
}

Log files are append-only and never overwritten. Safe to commit to your repository.

---

qa-safety.js

Property	Value
Event	PreToolUse
Language	Node.js
Exit 0	Allow tool call
Exit 2	Block tool call

The most complex hook. Evaluates every tool call before it executes. See Hooks & Safety Guards for the full allow/block reference.

---

session-start (bash)

Property	Value
Event	SessionStart
Language	bash

Injects the skill index into the coding-agent context at session start. The index includes:

• Lifecycle order of all 15 skills
• Config contract (what dq-qa.config.json must contain)
• Phase gate rules

This ensures the coding agent has full plugin context from the very first message, without the user needing to explain the system.

---

stop (bash)

Property	Value
Event	Stop
Language	bash

Emits a progress summary and token/cost status line when the Claude session ends. Helps teams track API usage per QA cycle.

---

Windows support

All hooks are invoked via hooks/run-hook.cmd, a thin bash wrapper that works on both Unix and Windows (Git Bash / WSL).