t1k:hook-creator
| Field | Value |
|---|---|
| Module | t1k-maintainer |
| Version | 4.10.58 |
| Effort | medium |
| Tools | AskUserQuestion, Bash, Edit, Glob, Grep, Read, Write |
Keywords: create hook, hook claim, hook creator, hook registration, hook script, new hook, scaffold hook, update hook
How to invoke
Section titled “How to invoke”/t1k:hook-creator[hook-name] [create|update|claim|validate]Hook Creator
Section titled “Hook Creator”Authoring checklist for .claude/hooks/*.cjs. The canonical executor is t1k-hooks-manager —
that agent owns hook authoring, claim placement, and the three-axis check; this skill is the shape it
works from. Where the two disagree, the agent body is right and this file is the bug.
Before authoring: decide whether this belongs in a .cjs at all — rules/ai-driven-design.md
(judgment → skill, deterministic → script).
A hook is not one file. It is five things, and a hook missing any of them is inert:
| # | Piece | Miss it and |
|---|---|---|
| 1 | The .cjs itself | — |
| 2 | hook-runner.cjs gateway routing | your hook bypasses dedup and double-fires |
| 3 | Registration (settings.json, then regenerate the derived manifest) | it never runs — present, not wired |
| 4 | module.json claim (or deliberately SHARED) | it ships to the wrong consumers, or to none |
| 5 | A test that goes red when the hook breaks | nothing re-checks it after this PR |
The five pieces
Section titled “The five pieces”2 — Gateway. All hooks execute through hook-runner.cjs; it applies dedupGuard() (MD5 lock, 3s
window) so a global + project double-install does not double-run. Never add a direct settings.json
command that skips the gateway.
3 — Registration. Required kit-shipped hooks are declared in
scripts/required-hook-registrations.json ({event, matcher, hookName}), and consumers reconcile
theirs on t1k modules update. Never hand-roll a settings.json registration when that file is the
SSOT — keep the two in sync and say which one you changed. A broken wiring is FAIL, not WARN.
Check the matcher covers the event you need: Task|Agent, Bash, PostToolUse/Edit|Write|MultiEdit
— and remember a matcher naming a closed tool set cannot cover every write path.
4 — Claim. Resolve with grep -n "<hook-or-lib>" .claude/modules/*/module.json:
| Result | Meaning |
|---|---|
| no hit | SHARED — ships in the shared ZIP to every consumer |
files.hooks[] / files.scripts[] | claimed — only consumers of that module get it |
sharedAlso[] | claimed and still shared |
Unclaimed is the accepted steady state for a hooks/lib/*.cjs required kit-wide (e.g. doctor-check-context.cjs, required by 13 doctor checks). Claim a lib (with sharedAlso) only when a claimed hook’s project-scope copy must run without the shared ZIP (the statusline lib closure, core#3372).
Find consumers by grepping the whole .claude/ tree, never hooks/ alone — a skill script can
require a lib you thought was hook-only. Then the invariant: a required: true module may never
hard-depend on an opt-in module’s claimed file. Every module.json edit is followed by regenerating
.claude/t1k-modules.json in the same commit (agents/t1k-kit-developer.md § Module Registry Sync).
5 — Test. A hook with no test violates core requirement #13, and P1’s own bug list names it:
auto-lesson-from-skill-edit.cjs shipped with zero coverage. Prefer pinning the failure states —
a check never seen failing is unproven (rules/green-that-proves-nothing.md) — and assert the
process exit code, not log text.
Hook health budget (enforced, not advisory)
Section titled “Hook health budget (enforced, not advisory)”Every hook is a process on a hot path: one Bash call once launched 56-64 bun -e launchers because
per-hook entries coexisted with the batch entries covering the same hooks (PreToolUse has no dedup, so the
hook ran twice). Rules, in full with the numbers in references/hook-health-budget.md:
- Gateway only. A manifest-covered hook is never given its own
bun -eentry in a consumer’s or the user’s settings.json, and never a second copy anywhere. A per-hook entry that a batch entry covers failsvalidate-hook-health(shadowed); identical entries fail (duplicate). - Declare it. Every PreToolUse/PostToolUse hook carries
@filter,@appliesWhen,@inprocessor// @everyCall: <reason>in its first 2 KB. The grandfather list (scripts/hook-health-grandfathered.json) may only shrink. - Filter only what you can prove. The acting condition is inside the filter, and every filter has a break-it test (a payload that must still reach the hook, an evasion form, one that is skipped).
- Cheap and clean. No heavy
requirebefore the early exit; no child/timer/handle that outlives the hook (everythingunref()’d, a hard self-timeout). - Measure. Count children per call with
T1K_GATEWAY_DEBUG=1before and after, and put it in the PR. Budget: a Bash PreToolUse call starts at most gateway+5 = 6 launchers once migrated (5 = the measured model-routermr-*set) (legacy ceiling 27, frozen) and at most 3 always-spawn hooks.
Gate: scripts/validate-hook-health.cjs (CI) and doctor check #101 (installs, FAIL).
No detached workers (policy 2026-11-18)
Section titled “No detached workers (policy 2026-11-18)”A hook never spawns a process that outlives it. The Stop event costs its slowest hook, so keep the work small: do it inline under a short timeout (spawnSync(..., {timeout}), a bounded walk budget), or drop it. The old lib/deferred-work.cjs primitive and its doctor check #102 are removed. Intentional daemons (MCP gateway, discord-inbound loop, model-router hops) are the only exceptions, and each file is listed with a reason in scripts/detached-spawn-allowlist.json (enforced by validate-hook-health).
Cross-platform & scope (non-negotiable)
Section titled “Cross-platform & scope (non-negotiable)”- Node +
path.join()+os.tmpdir()+process.platform. No bash, no shell strings. - Global-only mode works. Every hook resolves project context through
resolveProjectDir()— there is no project, and that is a supported state, not an error path (core requirement #6). - Read feature flags through the shared reader, not by re-parsing config.
- Fail open: a hook must never block tool execution because it threw. Report failure by return value.
Workflow
Section titled “Workflow”- State the claim question first — which module owns it, or SHARED, and why. Claim scope usually decides the shape.
- Author the
.cjs; keep it ≤200 lines and self-documenting at the top. - Register — gateway +
settings.json, thenbun .claude/scripts/generate-required-hook-registrations.cjs(the manifest is DERIVED; never hand-edit it). - Claim — apply the consumer-scope rule and the required-module invariant.
- Write the test; watch it go red against the broken shape before you call it green.
- Report per
t1k-hooks-manager§ Output contract, then runreferences/validation-checklist.md.
References
Section titled “References”references/validation-checklist.md— pre-merge checklist, including the## Lessons ledgerreferences/hook-health-budget.md— the health rules, budget numbers, and how to measure children per call.claude/agents/t1k-hooks-manager.md— the canonical agent (three-axis check, consumer-scope rule)rules/wired-not-just-present.md·rules/green-that-proves-nothing.md— cite, do not restate