07f02e77db
New optional command between /ultraresearch-local and /ultraplan-local that matches brief+research against Claude Code features (hooks, subagents, skills, output-styles, MCP, plan-mode, worktrees, background-agents) and produces an architecture note with brief-anchored rationale plus explicit gaps. Added: - commands/ultra-cc-architect-local.md (--project, --fg, --quick, --no-gaps) - agents/architect-orchestrator.md (opus) — 6-phase background orchestrator - agents/feature-matcher.md (sonnet) — fallback-ranked feature proposals - agents/gap-identifier.md (sonnet) — 4 gap classes with issue-ready drafts - agents/architecture-critic.md (sonnet) — hallucination gate as BLOCKER - skills/cc-architect-catalog/ — SKILL.md + 10 seed entries (reference/pattern) Changed (non-breaking): - commands/ultraplan-local.md — auto-discovers architecture/overview.md - agents/planning-orchestrator.md — cross-references cc_features_proposed - plugin.json — 2.1.0 → 2.2.0, description, cc-architecture keyword - CHANGELOG, README, CLAUDE.md (plugin + marketplace root) Pipeline becomes brief → research → architect → plan → execute. Architect is optional; existing project dirs keep working unchanged. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
89 lines
3.3 KiB
Markdown
89 lines
3.3 KiB
Markdown
---
|
|
name: hooks-pattern
|
|
description: When to choose hooks over prompts or subagents, and common hook shapes that work.
|
|
layer: pattern
|
|
cc_feature: hooks
|
|
source: https://docs.claude.com/en/docs/claude-code/hooks
|
|
concept: hooks-decision-and-shapes
|
|
last_verified: 2026-04-18
|
|
ngram_overlap_score: null
|
|
review_status: 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".
|