From 2567281846e07c7a36a91fae2b21393f2c88af04 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 8 Jan 2026 09:33:31 +0000
Subject: [PATCH] docs: document hook model overrides

---
 CHANGELOG.md                    |  1 +
 docs/automation/gmail-pubsub.md |  4 ++++
 docs/automation/webhook.md      | 15 +++++++++++++++
 docs/gateway/configuration.md   |  4 +++-
 4 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index aab2b2803..5a97d656c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,7 @@
 ## Unreleased
 
 - WhatsApp: group `/model list` output by provider for scannability. (#456) - thanks @mcinteerj
+- Hooks: allow per-hook model overrides for webhook/Gmail runs (e.g. GPT 5 Mini).
 
 ## 2026.1.8
 
diff --git a/docs/automation/gmail-pubsub.md b/docs/automation/gmail-pubsub.md
index f3cf30a4c..d09e3c0ee 100644
--- a/docs/automation/gmail-pubsub.md
+++ b/docs/automation/gmail-pubsub.md
@@ -49,6 +49,7 @@ that sets `deliver` + optional `provider`/`to`:
         sessionKey: "hook:gmail:{{messages[0].id}}",
         messageTemplate:
           "New email from {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}\n{{messages[0].body}}",
+        model: "openai/gpt-5.2-mini",
         deliver: true,
         provider: "last"
         // to: "+15551234567"
@@ -61,6 +62,9 @@ that sets `deliver` + optional `provider`/`to`:
 If you want a fixed channel, set `provider` + `to`. Otherwise `provider: "last"`
 uses the last delivery route (falls back to WhatsApp).
 
+To force a cheaper model for Gmail runs, set `model` in the mapping
+(`provider/model` or alias). If you enforce `agent.models`, include it there.
+
 To customize payload handling further, add `hooks.mappings` or a JS/TS transform module
 under `hooks.transformsDir` (see [`docs/webhook.md`](https://docs.clawd.bot/automation/webhook)).
 
diff --git a/docs/automation/webhook.md b/docs/automation/webhook.md
index 680e505f0..6f568bf64 100644
--- a/docs/automation/webhook.md
+++ b/docs/automation/webhook.md
@@ -60,6 +60,7 @@ Payload:
   "deliver": false,
   "provider": "last",
   "to": "+15551234567",
+  "model": "openai/gpt-5.2-mini",
   "thinking": "low",
   "timeoutSeconds": 120
 }
@@ -72,6 +73,7 @@ Payload:
 - `deliver` optional (default `false`)
 - `provider` optional: `last` | `whatsapp` | `telegram`
 - `to` optional (provider-specific target)
+- `model` optional (model override, `provider/model` or alias; must be allowed if `agent.models` is set)
 - `thinking` optional (override)
 - `timeoutSeconds` optional
 
@@ -121,6 +123,19 @@ curl -X POST http://127.0.0.1:18789/hooks/agent \
   -d '{"message":"Summarize inbox","name":"Email","wakeMode":"next-heartbeat"}'
 ```
 
+### Use a different model
+
+Add `model` to the agent payload (or mapping) to override the model for that run:
+
+```bash
+curl -X POST http://127.0.0.1:18789/hooks/agent \
+  -H 'x-clawdbot-token: SECRET' \
+  -H 'Content-Type: application/json' \
+  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.2-mini"}'
+```
+
+If you enforce `agent.models`, make sure the override model is included there.
+
 ```bash
 curl -X POST http://127.0.0.1:18789/hooks/gmail \
   -H 'Authorization: Bearer SECRET' \
diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md
index cc0ebc641..97d3aa525 100644
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -1692,6 +1692,7 @@ Defaults:
           "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}",
         deliver: true,
         provider: "last",
+        model: "openai/gpt-5.2-mini",
       },
     ],
   }
@@ -1705,7 +1706,7 @@ Requests must include the hook token:
 
 Endpoints:
 - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }`
-- `POST /hooks/agent` → `{ message, name?, sessionKey?, wakeMode?, deliver?, provider?, to?, thinking?, timeoutSeconds? }`
+- `POST /hooks/agent` → `{ message, name?, sessionKey?, wakeMode?, deliver?, provider?, to?, model?, thinking?, timeoutSeconds? }`
 - `POST /hooks/<name>` → resolved via `hooks.mappings`
 
 `/hooks/agent` always posts a summary into the main session (and can optionally trigger an immediate heartbeat via `wakeMode: "now"`).
@@ -1717,6 +1718,7 @@ Mapping notes:
 - `transform` can point to a JS/TS module that returns a hook action.
 - `deliver: true` sends the final reply to a provider; `provider` defaults to `last` (falls back to WhatsApp).
 - If there is no prior delivery route, set `provider` + `to` explicitly (required for Telegram/Discord/Slack/Signal/iMessage).
+- `model` overrides the LLM for this hook run (`provider/model` or alias; must be allowed if `agent.models` is set).
 
 Gmail helper config (used by `clawdbot hooks gmail setup` / `run`):