From 7dcedca323ece91608642dbedbe546b9ded24ec1 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 3 Jan 2026 02:32:37 +0100
Subject: [PATCH] fix: prioritize explicit hook mappings

---
 CHANGELOG.md                 | 1 +
 docs/configuration.md        | 1 +
 docs/webhook.md              | 1 +
 src/gateway/hooks-mapping.ts | 2 +-
 4 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d1011cc52e..96ad80cb1a 100644
--- a/CHANGELOG.md
+++ b/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.*`:
diff --git a/docs/configuration.md b/docs/configuration.md
index 12b266e72f..ce29132640 100644
--- a/docs/configuration.md
+++ b/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.
 
diff --git a/docs/webhook.md b/docs/webhook.md
index b72b407747..42c157bb04 100644
--- a/docs/webhook.md
+++ b/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.
diff --git a/src/gateway/hooks-mapping.ts b/src/gateway/hooks-mapping.ts
index 0824b9a02e..3ec33a7d31 100644
--- a/src/gateway/hooks-mapping.ts
+++ b/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);