From c7b336d83e13a44678a155bda40098d7d33b8232 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Sat, 25 Apr 2026 18:38:27 -0700 Subject: [PATCH] docs(hooks): document new ctx.jobId field on plugin hook contexts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Scott Glover's commit 371b69b3e2 ('Expose cron jobId in plugin hook context') added an optional jobId field on PluginHookAgentContext, populated for cron-driven runs. The commit shipped without a docs update or CHANGELOG entry, so plugin authors had no visible signal that the new ctx.jobId field exists. Surface ctx.jobId in two existing hook context references in docs/plugins/hooks.md: the before_tool_call ctx-fields list, and the runId/agent-lifecycle paragraph that already names ctx.runId — extend it to note ctx.jobId on cron-driven runs and what plugins can do with it (scope metrics, side effects, or state to a scheduled job). --- docs/plugins/hooks.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/plugins/hooks.md b/docs/plugins/hooks.md index abd5a3e2e28..a46129680ea 100644 --- a/docs/plugins/hooks.md +++ b/docs/plugins/hooks.md @@ -112,8 +112,8 @@ observation-only. - `event.params` - optional `event.runId` - optional `event.toolCallId` -- context fields such as `ctx.agentId`, `ctx.sessionKey`, `ctx.sessionId`, and - diagnostic `ctx.trace` +- context fields such as `ctx.agentId`, `ctx.sessionKey`, `ctx.sessionId`, + `ctx.runId`, `ctx.jobId` (set on cron-driven runs), and diagnostic `ctx.trace` It can return: @@ -178,6 +178,9 @@ so your plugin does not depend on a legacy combined phase. `before_agent_start` and `agent_end` include `event.runId` when OpenClaw can identify the active run. The same value is also available on `ctx.runId`. +Cron-driven runs also expose `ctx.jobId` (the originating cron job id) so +plugin hooks can scope metrics, side effects, or state to a specific scheduled +job. Use `model_call_started` and `model_call_ended` for provider-call telemetry that should not receive raw prompts, history, responses, headers, request