Hook Distribution

Defines how A11YSmith hook enforcement is built, distributed, and consumed across platforms.

Architecture Decision

Hooks are authored in TypeScript and compiled to JavaScript artifacts for distribution. Platforms that cannot execute JS receive advisory fallback instructions.

Build Pipeline

packages/agents/src/engine/hook-engine.ts (TS source)
  → pnpm turbo build
  → packages/agents/dist/engine/hook-engine.js (compiled JS)
  → generators consume compiled output
  → platform-specific hook configs reference the JS artifact

Platform-Specific Distribution

Claude Code

Format: hooks.json (or .claude/hooks/ directory)

Hooks are distributed as shell commands that invoke the compiled JS:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "command": "node /path/to/hook-engine.js user-prompt-submit"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "node /path/to/hook-engine.js pre-tool-use"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Agent",
        "command": "node /path/to/hook-engine.js post-tool-use"
      }
    ]
  }
}

The generator (packages/agents/src/generators/claude-code/) produces this config from the hook engine's exported functions.

GitHub Copilot

Format: copilot-instructions.md + copilot-review-instructions.md

Copilot does not support programmatic hooks. The generator produces advisory instructions that describe the same enforcement behavior as prose guidance.

Gemini

Format: SKILL.md files in .gemini/extensions/

Gemini skills include advisory enforcement instructions in each skill file.

VS Code Extension

Format: Extension activation events

The VS Code extension wrapper can invoke hook-engine.js through extension API calls.

Fallback Behavior

When a platform cannot execute the compiled JS hook:

1. Generator produces advisory instructions describing the enforcement behavior
2. Advisory instructions include the same decision logic as the programmatic hook
3. The advisory approach relies on the AI model following instructions rather than programmatic enforcement
4. Advisory fallback is clearly marked as non-enforcing in generated output

Security Requirements

• Hook scripts must not execute arbitrary user input
• Hook scripts must not read or transmit credentials, tokens, or PII
• Hook scripts must fail open (deny → allow) rather than blocking the user indefinitely
• Hook configuration files must be version-controlled and reviewable

Current Status

The hook engine (packages/agents/src/engine/hook-engine.ts) has working logic for:

• isUiFile() — detects web UI files by extension
• handleUserPromptSubmit() — injects accessibility delegation instruction
• handlePreToolUse() — blocks UI edits until accessibility-lead reviewed
• handlePostToolUse() — marks session as reviewed after accessibility-lead completes

The generateHooksConfig() function currently produces echo-stub output. Phase 1 (Epic 2.5) will upgrade it to emit the compiled JS artifact reference.