fix: prioritize explicit hook mappings

CHANGELOG.md

@@ -7,6 +7,7 @@
 - Agent runtime: update pi-mono dependencies to 0.31.1 (agent-core split).
 - Dependencies: bump to latest compatible versions (TypeBox, grammY, Zod, Rolldown, oxlint-tsgolint).
 - Tests: cover read tool image metadata + text output.
+- Hooks: treat null transforms as handled skips (204) and let explicit mappings override presets (#117) — thanks @jverdi.
 
 ### Breaking
 - Skills config schema moved under `skills.*`:

docs/configuration.md

@@ -701,6 +701,7 @@ Endpoints:
 Mapping notes:
 - `match.path` matches the sub-path after `/hooks` (e.g. `/hooks/gmail` → `gmail`).
 - `match.source` matches a payload field (e.g. `{ source: "gmail" }`) so you can use a generic `/hooks/ingest` path.
+- `hooks.mappings` are evaluated before presets; first match wins.
 - Templates like `{{messages[0].subject}}` read from the payload.
 - `transform` can point to a JS/TS module that returns a hook action.
 

docs/webhook.md

@@ -89,6 +89,7 @@ code transforms.
 Mapping options (summary):
 - `hooks.presets: ["gmail"]` enables the built-in Gmail mapping.
 - `hooks.mappings` lets you define `match`, `action`, and templates in config.
+- `hooks.mappings` are evaluated before presets; first match wins.
 - `hooks.transformsDir` + `transform.module` loads a JS/TS module for custom logic.
 - Use `match.source` to keep a generic ingest endpoint (payload-driven routing).
 - TS transforms require a TS loader (e.g. `tsx`) or precompiled `.js` at runtime.

src/gateway/hooks-mapping.ts

@@ -114,11 +114,11 @@ export function resolveHookMappings(
 ): HookMappingResolved[] {
   const presets = hooks?.presets ?? [];
   const mappings: HookMappingConfig[] = [];
+  if (hooks?.mappings) mappings.push(...hooks.mappings);
   for (const preset of presets) {
     const presetMappings = hookPresetMappings[preset];
     if (presetMappings) mappings.push(...presetMappings);
   }
-  if (hooks?.mappings) mappings.push(...hooks.mappings);
   if (mappings.length === 0) return [];
 
   const configDir = path.dirname(CONFIG_PATH_CLAWDIS);