PR #78655: fix: surface hook model rejection diagnostics

• Repository: openclaw/openclaw
• Author: kevinslin
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/78655

Description (problem / solution / changelog)

Summary

• Problem: /hooks/agent could accept a run whose payload.model was rejected by the cron model allowlist, then only surface a quiet returned error path.
• Why it matters: operators saw HTTP 200/runId but no transcript, no model call, and no obvious Gateway warning for the rejected model.
• What changed: hook-triggered isolated-run errors now log a structured gateway/hooks warning, direct failed cron jobs now log a scheduler warning with the diagnostic summary, and hook announcements prefer cron diagnostic summaries.
• What did NOT change (scope boundary): explicit disallowed payload.model values still fail closed; hook HTTP semantics still return an async run id.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #78597
• Related #75928
• This PR fixes a bug or regression

Real behavior proof

• Behavior or issue addressed: disallowed /hooks/agent payload.model is discoverable at the hook boundary.

• Real environment tested: local isolated integration Gateway from this branch, workspace issue-78597-fixed, port 54506.

• Exact steps or command run after this patch: started ./.mem/integ/scripts/run_integ_gateway.mjs issue-78597-fixed 54506, POSTed /hooks/agent with model: "anthropic/claude-sonnet-4-6" while only openai/gpt-5.5 was in agents.defaults.models, then checked the Gateway log.

• Evidence after fix: .mem/main/integ/issue-78597-fixed.md verifies hook_warning_lines=1 and diagnostic_summary_lines=2. After-fix console output from the real integration Gateway run:

  hook_http_status=200
  hook_returned_run_id=yes
  hook_warning_lines=1
  diagnostic_summary_lines=2
  session_or_transcript_files=1
  issue_fixed=yes
  
  gateway/hooks hook agent run returned non-ok status
  status=error
  model=anthropic/claude-sonnet-4-6
  sessionKey=hook:issue-78597
  summary=cron payload.model 'anthropic/claude-sonnet-4-6' rejected by agents.defaults.models allowlist: anthropic/claude-sonnet-4-6

• Observed result after fix: Gateway log includes hook agent run returned non-ok status with model, session key, run id, job id, and the cron allowlist rejection summary.

• What was not tested: real model delivery of the follow-up announcement, because the isolated proof workspace intentionally had no OpenAI auth profile.

• Before evidence: .mem/main/integ/issue-78597-repro.md records HTTP 200 with run id, zero session/transcript files, and zero hook/model rejection warning lines before the patch.

Root Cause

• Root cause: /hooks/agent dispatches isolated cron-style work asynchronously and only logged thrown exceptions, while disallowed payload.model is a returned status: "error" result before the agent runner starts.
• Missing detection / guardrail: hook tests asserted the quiet system event but not logHooks.warn, and cron tests did not pin the preflight diagnostic object for disallowed payload models.
• Contributing context: #75928 added cron diagnostics, but the hook boundary was still summarizing returned errors without logging them.

Regression Test Plan

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/gateway/server/hooks.agent-trust.test.ts and src/cron/isolated-agent/run.cron-model-override.test.ts.
• Scenario the test should lock in: returned hook status: "error" uses cron diagnostic summaries for announcements and emits a structured warning; failed cron job results log their diagnostic summary; disallowed cron payload model carries cron-preflight diagnostics.
• Why this is the smallest reliable guardrail: it exercises the exact returned-error seam without needing live model credentials.
• Existing test that already covers this (if any): existing hook trust tests covered announcement trust, but not warning visibility or diagnostic-summary precedence.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

Rejected hook-triggered cron model overrides now produce a visible Gateway warning and a more specific hook announcement summary. Direct failed cron jobs now also produce a scheduler warning with the stored diagnostic summary.

Diagram

Before:
/hooks/agent -> async isolated run -> payload.model rejection -> quiet returned error

After:
/hooks/agent -> async isolated run -> payload.model rejection -> cron diagnostic summary -> hook warning + announcement summary
cron job -> isolated run -> payload.model rejection -> cron diagnostic summary -> cron warning + job state

Security Impact

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS local development host
• Runtime/container: Node 25.6.0 via repo scripts
• Model/provider: configured allowlist openai/gpt-5.5; rejected payload model anthropic/claude-sonnet-4-6
• Integration/channel: local /hooks/agent
• Relevant config (redacted): hooks enabled with local token, hooks.defaultSessionKey = "hook:issue-78597", agents.defaults.models["openai/gpt-5.5"] = {}

Steps

1. Create isolated integration workspace and enable hooks.
2. Start Gateway on a random loopback port.
3. POST /hooks/agent with a payload model outside agents.defaults.models.
4. Inspect Gateway logs and state artifacts.

Expected

• Rejected payload model is visible in hook diagnostics/logging.

Actual

• Before patch: HTTP 200/run id, no transcript, no hook/model rejection warning.
• After patch: HTTP 200/run id, plus a structured gateway/hooks warning with the cron diagnostic summary.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification

• Verified scenarios: targeted tests, changed checks, changed tests, repro Showboat proof, fixed Showboat proof.
• Edge cases checked: hook diagnostic summary takes precedence over generic summary/error; cron preflight diagnostic source/severity is preserved.
• What you did not verify: authenticated delivery of the follow-up announcement in a live channel.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: warning volume increases for non-ok hook runs that were already being announced.
  • Mitigation: only returned non-ok isolated hook results warn; successful delivered and suppressed runs are unchanged.

Verification

• pnpm test src/cron/isolated-agent/run.cron-model-override.test.ts src/gateway/server/hooks.agent-trust.test.ts -- --reporter=dot
• pnpm test src/cron/service/timer.regression.test.ts src/cron/isolated-agent/run.cron-model-override.test.ts -- --reporter=dot
• pnpm exec oxfmt --check --threads=1 src/gateway/server/hooks.ts src/gateway/server/hooks.agent-trust.test.ts src/cron/isolated-agent/run.cron-model-override.test.ts CHANGELOG.md
• git diff --check
• uvx showboat verify /Users/kevinlin/code/openclaw/.mem/main/integ/issue-78597-repro.md
• uvx showboat verify /Users/kevinlin/code/openclaw/.mem/main/integ/issue-78597-fixed.md
• pnpm check:changed
• pnpm test:changed

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/cron/isolated-agent/run.cron-model-override.test.ts (modified, +10/-0)
• src/cron/service/timer.regression.test.ts (modified, +12/-2)
• src/cron/service/timer.ts (modified, +11/-0)
• src/gateway/server/hooks.agent-trust.test.ts (modified, +110/-0)
• src/gateway/server/hooks.ts (modified, +62/-4)