Hooks Guide

Guide Origin: Official | ArcKit Version: [VERSION]

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

Overview

Event	Hooks	When it fires
SessionStart	arckit-session, version-check, v5-migration-banner, notify-stale-artifacts	Session start, resume, clear, compact
Stop	session-learner	Session ends normally
StopFailure	session-learner	Session ends with error
UserPromptSubmit	arckit-context, secret-detection, sync-guides, graph-inject	Every user message and matched ArcKit commands
SubagentStart	inject-agent-context	An ArcKit subagent starts (not readers or writers)
PreToolUse	validate-reader-handoff (SubagentHandback), validate-arc-filename, score-validator, validate-wardley-math, file-protection, secret-file-scanner	Before selected tool calls
PostToolUse	update-manifest, provenance-stamp, tidy-wardley-labels, telemetry	After selected tool calls
TaskCreated	telemetry	When an agent task is created
FileChanged	external-context-watch	Watched external documents change
PostCompact	postcompact-rehydrate	After context compaction

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
• projects/*/external/ directories to watch for mid-session evidence changes

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.

FileChanged Hooks

external-context-watch

arckit-session registers every existing projects/*/external/ directory as a dynamic watch path at session start. external-context-watch injects refreshed project context when a watched external document is added, changed, or removed, and refreshes the watch list so newly created nested external directories are picked up after the next file-change event.

This means a briefing, transcript, vendor pack, regulation, or architecture note dropped into external/ mid-session is surfaced to Claude without waiting for a restart, /compact, or another /arckit: command. README files inside external/ are ignored.

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 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 if invalid, and the reason names the corrected path, with the next sequence number and the right subfolder already worked out. Claude then writes the same content there. The hook never changes the write itself.

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 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 for details.

SubagentStart Hooks

inject-agent-context

When an ArcKit subagent starts, such as the framework agent, it gets the same project context your own prompts get: the projects, their artefacts, vendor profiles, external documents and global policies. Reader and writer subagents are left out, because they take strict JSON. Other plugins' agents and Claude Code's own agents are never touched.

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 }.

TaskCreated Hooks

telemetry

Records ArcKit agent spawns so session summaries can show which subagents ran and how much tool activity they performed.

PostCompact Hooks

postcompact-rehydrate

Re-injects the same project inventory used by arckit-context after manual or automatic compaction so dynamic project state is not lost from the context window.

Permissions

No ArcKit hook approves a permission request. Each command and skill declares what it needs in its own allowed-tools frontmatter, and Claude Code applies those rules only while it runs.

• ArcKit's own files (templates, references, schemas) are pre-approved for reading by Read(/${CLAUDE_PLUGIN_ROOT}/**), because every command reads its templates from the plugin's install directory, outside your project.

• ArcKit's own scripts (document IDs, project creation, Wardley rendering, OKF import and export) are pre-approved by each command's allowed-tools rules. Claude Code checks those per command, so a script call chained to anything else still asks.

• MCP tool calls ask the first time. To stop the prompts for a server you trust, add it to permissions.allow in your settings, for example "mcp__plugin_arckit_aws-knowledge" or "mcp__plugin_arckit_microsoft-learn".

• Research reader output is checked by validate-reader-handoff (PostToolUse on Agent, and PreToolUse on SubagentHandback in auto mode), with no shell command and no permission.

Utility Files

These are shared libraries, not hooks themselves:

File	Purpose
hook-utils.mjs	Shared utilities: parseHookInput(), findRepoRoot(), extractDocType(), file I/O helpers
external-context-utils.mjs	Shared helpers for external-document watch paths and path filtering
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.