ktg-plugin-marketplace/plugins/ultraplan-local/skills/cc-architect-catalog/hooks-pattern.md

name	description	layer	cc_feature	source	concept	last_verified	ngram_overlap_score	review_status
hooks-pattern	When to choose hooks over prompts or subagents, and common hook shapes that work.	pattern	hooks	https://docs.claude.com/en/docs/claude-code/hooks	hooks-decision-and-shapes	2026-04-18	null	approved

Hooks — Pattern

When to reach for a hook

Use hooks when the behavior must hold even if Claude is prompt-injected, distracted, or adversarial. Hooks are outside the model's control loop — Claude cannot talk its way past them.

Good fits:

• Hard prohibitions — "never run rm -rf /", "never push to main without a commit signature", "never read files outside this repo".
• Deterministic context injection — always show git status at session start; always inject the current sprint's tasks.
• Audit trails — log every Bash call, every file write, outside the conversation context so it survives /clear.
• Compliance boundaries — redact secrets from transcripts; block tool calls that would leak PII.

Bad fits:

• Behavior that requires judgment ("should this test run?") — that's a subagent call.
• Heuristics that drift ("mostly block, sometimes allow") — a hook that frequently second-guesses itself is a sign the rule belongs in a prompt or skill.
• Anything that needs to read lots of conversation history — hooks see a payload, not the full context.

Common shapes

Shape A: PreToolUse deny

A small script that reads tool_input, matches a pattern, and exits with a block decision. Latency: a few ms. Used for command denylists, path guards, secrets scanners.

Shape B: UserPromptSubmit context injection

A script that reads the prompt, computes context (e.g., recent git log, active TODO list), and emits JSON with an additionalContext field. The harness adds that context to the prompt before Claude sees it.

Shape C: Stop hook with reminder

A script that runs when Claude finishes a turn. Checks for uncommitted work, surfaces it as a notification. Non-blocking.

Shape D: SessionStart status

Runs once per session. Prints repo metadata (branch, open PRs, recent commits) so every new session starts with shared context.

Pitfalls

• Slow hooks compound. A 500 ms PreToolUse hook run 50 times per session adds 25 seconds of latency.
• Hooks without error handling crash the turn. A hook that exits non-zero on an edge case blocks real work. Default to exit 0 with a logged warning.
• Shell-injection in hook scripts. A hook that interpolates tool_input.command into bash -c is itself a security hole. Parse inputs; never interpolate unescaped.
• Hooks can leak secrets into transcripts if their output mentions env-var values. Scrub before emitting.
• Cross-platform scripts. A hook that assumes bash 4 or GNU sed breaks on macOS. Prefer Node.js, Python, or POSIX sh.

Composition with other features

• Hooks + subagents: a hook can delegate the "should this be blocked" question to a subagent when the decision needs judgment. Cost: a full model call per hook invocation — use sparingly.
• Hooks + MCP: a hook can call out to an MCP-exposed tool for policy lookup. Latency depends on transport.
• Hooks + plan mode: hooks fire during plan mode too. Useful for enforcing "no writes while planning".