Coding Agents Hooks Authoring

<hooks_authoring>

Hook entry rule

Only files that export defineHook(…) AND call runAsCli(hook, module) belong directly in src/hooks/src/hooks/. Every .ts at the top level of that directory becomes a standalone CJS bundle distributed to all 6 IDE targets (claude-code, codex, copilot, cursor, windsurf, antigravity). Helper/data files without runAsCli belong in a named subdirectory: src/hooks/src/hooks/<feature>/.

Helper placement

• Feature-local helpers → src/hooks/src/hooks/<feature>/ (e.g. src/hooks/src/hooks/dangerous-actions/patterns.ts).
• Cross-hook runtime helpers → src/hooks/src/runtime/.

Build is non-recursive

src/hooks/scripts/build-bundles.mjs:29 uses readdirSync(hooksDir).filter(f => f.endsWith('.ts')). There is no { recursive: true }. Subdirectories are invisible to the bundler. Adding a top-level .ts without runAsCli produces a dead bundle for every plugin. A plugin may opt a hook OUT via excludeHooks in the PLUGINS array (build-bundles.mjs) — e.g. core-antigravity excludes the advise-only hooks, which have no delivery channel there.

Adding a SemanticKind

When a hook needs a new tool category (e.g. mcp-call):

1. src/hooks/src/runtime/ide-registry.ts — add a row to TOOL_KINDS with all 6 IDE columns (null where the event doesn't exist). SemanticKind = keyof typeof TOOL_KINDS so TypeScript enforces coverage.
2. src/hooks/src/runtime/ide-rows/<ide>.ts — if the kind requires special logic (e.g. prefix-match for mcp__.*), add a conditional branch at the top of lookupToolKind in the IDE-row file before the table loop. Table-driven lookup alone cannot handle open-ended tool name patterns.
3. Hook entry — add the new kind to def.on.toolKinds.
4. Matcher in hooks.json.tmpl — widen to include new tool names/patterns.

Order matters: run-hook.ts:316 gates on toolKinds before calling def.run(ctx). Matcher passes the event in; toolKinds must include the mapped kind or the call is dropped silently.

Registration

Every new hook must appear in each registering plugin's hooks.json. The canonical sources are the hooks.json.tmpl templates; direct edits to generated hooks.json files are overwritten on the next npx rosettify-plugins run.

Template paths by plugin, all under src/rosettify-plugins/plugins/ (templates are generator input only — .tmpl files are not emitted into the generated plugins/ tree):

• core-claude/hooks/hooks.json.tmpl
• core-codex/.codex-plugin/hooks.json.tmpl
• core-copilot/hooks/hooks.json.tmpl (+ core-copilot/.github/plugin/hooks.json.tmpl)
• core-cursor/hooks.json.tmpl (+ core-cursor/hooks/hooks.json.tmpl)