Skip to content

t1k:hook-creator

FieldValue
Modulet1k-maintainer
Version4.10.58
Effortmedium
ToolsAskUserQuestion, Bash, Edit, Glob, Grep, Read, Write

Keywords: create hook, hook claim, hook creator, hook registration, hook script, new hook, scaffold hook, update hook

/t1k:hook-creator
[hook-name] [create|update|claim|validate]

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:

#PieceMiss it and
1The .cjs itself—
2hook-runner.cjs gateway routingyour hook bypasses dedup and double-fires
3Registration (settings.json, then regenerate the derived manifest)it never runs — present, not wired
4module.json claim (or deliberately SHARED)it ships to the wrong consumers, or to none
5A test that goes red when the hook breaksnothing re-checks it after this PR

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:

ResultMeaning
no hitSHARED — 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:

  1. Gateway only. A manifest-covered hook is never given its own bun -e entry 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 fails validate-hook-health (shadowed); identical entries fail (duplicate).
  2. Declare it. Every PreToolUse/PostToolUse hook carries @filter, @appliesWhen, @inprocess or // @everyCall: <reason> in its first 2 KB. The grandfather list (scripts/hook-health-grandfathered.json) may only shrink.
  3. 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).
  4. Cheap and clean. No heavy require before the early exit; no child/timer/handle that outlives the hook (everything unref()’d, a hard self-timeout).
  5. Measure. Count children per call with T1K_GATEWAY_DEBUG=1 before 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-router mr-* 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).

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

  • 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.
  1. State the claim question first — which module owns it, or SHARED, and why. Claim scope usually decides the shape.
  2. Author the .cjs; keep it ≤200 lines and self-documenting at the top.
  3. Register — gateway + settings.json, then bun .claude/scripts/generate-required-hook-registrations.cjs (the manifest is DERIVED; never hand-edit it).
  4. Claim — apply the consumer-scope rule and the required-module invariant.
  5. Write the test; watch it go red against the broken shape before you call it green.
  6. Report per t1k-hooks-manager § Output contract, then run references/validation-checklist.md.
  • references/validation-checklist.md — pre-merge checklist, including the ## Lessons ledger
  • references/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