AIWG Hook Patterns

Issues: #284, #289 Version: 2026.2.0 Status: Active

Overview

Claude Code hooks enable AIWG to inject context dynamically and enforce quality gates without bloating CLAUDE.md. This guide covers PreToolUse context injection (#284) and extended timeout quality gates (#289).

PreToolUse Context Injection (#284)

Problem

AIWG loads all conventions via CLAUDE.md and path-scoped rules, consuming context window regardless of relevance. PreToolUse hooks can inject context only when a relevant tool is actually being used.

Pattern: Dynamic Context Loading

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "cat .aiwg/conventions/coding-standards.md 2>/dev/null || true",
        "additionalContext": true
      },
      {
        "matcher": "Bash",
        "command": "cat .aiwg/conventions/safety-checks.md 2>/dev/null || true",
        "additionalContext": true
      }
    ]
  }
}

How It Works

1. When Claude Code is about to use a tool (Write, Edit, Bash, etc.), the PreToolUse hook fires 2. The hook's `command` runs and its stdout becomes `additionalContext` 3. This context is injected into the model's next turn - targeted and temporary 4. No permanent context window cost - only loaded when relevant

AIWG Context Injection Examples

Coding conventions on Write/Edit:

# .aiwg/hooks/inject-coding-context.sh
#!/bin/bash
# Only inject if modifying source files
if echo "$TOOL_INPUT" | grep -q '"file_path".*"src/'; then
  cat .aiwg/conventions/typescript-standards.md
fi

Security checks on Bash:

# .aiwg/hooks/inject-safety-context.sh
#!/bin/bash
cat <<'CTX'
SAFETY REMINDER: Before executing commands:
- Never run destructive commands without confirmation
- Validate all file paths are within project scope
- Check for sensitive data exposure in output
CTX

Agent-specific context:

# .aiwg/hooks/inject-agent-context.sh
#!/bin/bash
AGENT=$(cat .aiwg/current-agent.txt 2>/dev/null)
if [ -f ".aiwg/conventions/${AGENT}.md" ]; then
  cat ".aiwg/conventions/${AGENT}.md"
fi

Benefits vs Static Loading

Approach	Context Cost	Relevance	Maintenance
CLAUDE.md (static)	Always loaded	May be irrelevant	Single file
Path-scoped rules	Per-file-type	Good	Multiple files
PreToolUse hooks	On-demand	Excellent	Hook scripts

Quality Gate Hooks (#289)

Problem

Previously, hooks timed out at 60 seconds - too short for running full test suites or security scans. Claude Code v2.1.3 extended timeouts to 10 minutes.

Pattern: Test Suite as Quality Gate

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "command": ".aiwg/hooks/run-affected-tests.sh",
        "timeout": 300000,
        "blocking": true
      }
    ]
  }
}

Hook script:

#!/bin/bash
# .aiwg/hooks/run-affected-tests.sh
# Run tests related to the file being modified

FILE=$(echo "$TOOL_INPUT" | python3 -c "import json,sys; print(json.load(sys.stdin).get('file_path',''))" 2>/dev/null)

if [[ "$FILE" == src/* ]]; then
  # Map source to test file
  TEST_FILE="${FILE/src\//test\/}"
  TEST_FILE="${TEST_FILE/.ts/.test.ts}"

  if [ -f "$TEST_FILE" ]; then
    npm test -- --testPathPattern="$TEST_FILE" --bail 2>&1
    exit $?
  fi
fi

exit 0  # No tests to run

Gate Types by Hook Phase

Gate	Hook Phase	Timeout	Purpose
Unit tests	PreToolUse(Write)	5 min	Validate before accepting changes
Security scan	PreToolUse(Bash)	10 min	Check commands before execution
Lint/format	PostToolUse(Write)	2 min	Auto-fix after writes
Coverage check	PostToolUse(Bash)	5 min	Verify coverage after test runs
SDLC gate	PreToolUse(Write)	5 min	Enforce phase requirements

SDLC Phase Gate Hook

#!/bin/bash
# .aiwg/hooks/sdlc-phase-gate.sh
# Enforce that required artifacts exist before construction phase

PHASE=$(cat .aiwg/planning/current-phase.txt 2>/dev/null || echo "unknown")

if [ "$PHASE" = "construction" ]; then
  MISSING=""
  [ ! -f .aiwg/architecture/sad.md ] && MISSING="$MISSING SAD"
  [ ! -f .aiwg/testing/test-strategy.md ] && MISSING="$MISSING TestStrategy"

  if [ -n "$MISSING" ]; then
    echo "GATE BLOCKED: Missing artifacts for construction:$MISSING"
    echo "Complete elaboration phase first."
    exit 1
  fi
fi

exit 0

Timeout Configuration

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "command": ".aiwg/hooks/quick-lint.sh",
        "timeout": 30000
      },
      {
        "matcher": "Bash",
        "command": ".aiwg/hooks/full-security-scan.sh",
        "timeout": 600000
      }
    ]
  }
}

Timeout guidelines:

Check Type	Recommended Timeout	Rationale
Lint/format	30s	Fast, single-file
Unit tests (affected)	2-5 min	Subset of tests
Full test suite	5-10 min	Complete validation
Security scan	5-10 min	Deep analysis
Build verification	3-5 min	Compilation check

Cross-Platform Notes

Hook patterns are Claude Code-specific. For other platforms:

Platform	Equivalent	Notes
Claude Code	`.claude/settings.json` hooks	Full support
GitHub Copilot	GitHub Actions	CI/CD based
Cursor	`.cursor/` rules	No hook equivalent
Warp	Warp workflows	Different mechanism

See `@docs/context-management-patterns.md` for cross-platform context strategies.

References

• @agentic/code/frameworks/sdlc-complete/agents/agent-template.md - Agent template hook section
• @.claude/rules/executable-feedback.md - Executable feedback integration
• @.claude/rules/hitl-gates.md - Quality gate rules
• `@docs/context-management-patterns.md` - Cross-platform context