# Hooks Guide

> **Guide Origin**: Official | **ArcKit Version**: [VERSION]

ArcKit's Claude Code plugin includes 17 automation hooks across 7 event types. Hooks run automatically — no manual configuration required.

## Overview

| Event | Hooks | When it fires |
|-------|-------|---------------|
| **SessionStart** | arckit-session, version-check | Session start, resume, clear, compact |
| **Stop** | session-learner | Session ends normally |
| **StopFailure** | session-learner | Session ends with error |
| **UserPromptSubmit** | arckit-context, secret-detection, + 6 command-specific | Every user message |
| **PreToolUse** | validate-arc-filename, score-validator, file-protection, secret-file-scanner | Before Write or Edit |
| **PostToolUse** | update-manifest | After Write |
| **PermissionRequest** | allow-mcp-tools | MCP tool permission prompt |

## SessionStart Hooks

### arckit-session

Fires once at session start (and on resume/clear/compact). Injects ArcKit plugin version into context and exports environment variables (`ARCKIT_VERSION`, `CLAUDE_CODE_NO_FLICKER=1`) for the session.

Also detects:

- Whether a `projects/` directory exists
- External files newer than the latest artifacts (prompts re-running commands)
- Recent session history from `.arckit/memory/sessions.md`

### version-check

Compares the local plugin version against the latest GitHub release tag. Shows a notification if an update is available.

## Stop / StopFailure Hooks

### session-learner

Fires when a session ends (both normal and failure). Records session activity — which projects were touched, what artifact types were created or modified — to `.arckit/memory/sessions.md` for context in future sessions.

## UserPromptSubmit Hooks

### arckit-context (all prompts)

Pre-computes project context when any `/arckit:` command is run. Injects project inventory, artifact lists, newest artifact timestamps, and ArcKit version via `additionalContext` so commands don't need to discover this themselves.

### secret-detection (all prompts)

Scans user prompts for secret patterns (API keys, tokens, passwords, connection strings, private keys). Blocks the message before it reaches the model if a secret is detected. See the [Security Hooks Guide](security-hooks.md) for details.

### Command-Specific Hooks

These fire only when the matched command is invoked:

| Hook | Fires on | Purpose |
|------|----------|---------|
| **sync-guides** | `/arckit:pages` | Syncs guide files, regenerates `docs/index.html` from the pages template, builds `docs/manifest.json` (including the v2 `dependencyGraph` with per-node `health` flags and the per-project `projectHealth` rollup that powers the dashboard's Project Health panel and Document Map tinting), and writes `docs/llms.txt` (llmstxt.org format) for LLM/agent discovery |
| **graph-inject** | `/arckit:search`, `/arckit:impact`, `/arckit:traceability`, `/arckit:health`, `/arckit:analyze`, `/arckit:navigator`, `/arckit:graph-report` | Single recipe-driven handler that builds the artifact graph via `graph-utils.mjs` and injects the right pre-extracted context per command — search index, dependency chains, traceability matrix, health findings, governance scan, navigator coverage, or graph-report metrics. Replaces the per-command `*-scan.mjs` handlers |

## PreToolUse Hooks

These fire before Claude writes or edits a file. They can block the operation.

### validate-arc-filename (Write)

Validates that files written to `projects/` follow the ARC naming convention (`ARC-{PID}-{TYPE}-v{VERSION}.md`). Checks:

- Project ID matches the directory number
- Document type is a known type code
- Version format is valid
- Multi-instance types (ADR, DIAG, etc.) have sequence numbers
- File goes in the correct subdirectory (e.g., ADRs in `decisions/`)

Blocks the write with a corrected filename suggestion if invalid.

### score-validator (Write)

Validates scoring/assessment documents for numeric consistency. Checks that individual scores match totals, percentages are calculated correctly, and rating scales are applied consistently.

### file-protection (Edit | Write)

Blocks writes to sensitive file paths — environment files (`.env`), credential stores, private keys, lock files, and CI/CD configuration. See the [Security Hooks Guide](security-hooks.md) for the full list.

### secret-file-scanner (Edit | Write)

Scans the content being written for embedded secret patterns. Catches cases where a secret is embedded in an otherwise safe file path. See the [Security Hooks Guide](security-hooks.md) for details.

## PostToolUse Hooks

### update-manifest (Write)

After a file is written to `projects/`, updates `docs/manifest.json` with the new artifact metadata (document ID, type, version, path, timestamp). This keeps the documentation site's artifact index in sync.

### provenance-stamp (Write | Edit)

After an ArcKit artifact is written or edited, stamps build provenance when the hook can derive build context or command effort. It can also add OKF-compatible frontmatter when explicitly enabled with `ARCKIT_OKF_FRONTMATTER=1` or `.arckit/config.json` containing `{ "okfFrontmatter": true }`.

## PermissionRequest Hooks

### allow-mcp-tools

Auto-allows MCP tool calls from ArcKit's bundled MCP servers (AWS Knowledge, Microsoft Learn, Google Developer Knowledge, DataCommons, govreposcrape, uk-tenders) so users don't need to approve each one manually.

## Utility Files

These are shared libraries, not hooks themselves:

| File | Purpose |
|------|---------|
| **hook-utils.mjs** | Shared utilities: `parseHookInput()`, `findRepoRoot()`, `extractDocType()`, file I/O helpers |
| **graph-utils.mjs** | Dependency graph construction (nodes, edges, requirements, principles, risks, vendors, externals) |
| **graph-rollups.mjs** | Shared health, coverage, and compliance computations: `tagNodeHealth()`, `computeAllProjectRollups()`, plus the canonical `ESSENTIAL_TYPES` / `HIGH_SEVERITY_TYPES` / `CONTEXTUAL_TYPES` / `STALE_THRESHOLD_DAYS` constants used by both `graph-inject` and `sync-guides` |
| **hooks.json** | Hook registration — maps events and matchers to handler commands |

## Troubleshooting

**Hook not firing?** Check that the hook is registered in `hooks.json` and the matcher pattern matches the tool or command name.

**Hook blocking unexpectedly?** PreToolUse hooks that exit with code 2 and output JSON with `"decision": "block"` will block the tool call. Check stderr output for the hook's reasoning.

**Timeout errors?** Each hook has a timeout (5–30 seconds) defined in `hooks.json`. Long-running invocations of `graph-inject` (e.g. for `/arckit:health` or `/arckit:analyze`) have 30-second timeouts. If a hook times out, it passes silently.