Summary

• Problem: tool progress callbacks during tool event emission could throw synchronously or reject asynchronously.
• Why it matters: a failing observer/progress callback could interrupt tool-start handling or leak an unhandled rejection in gateway runs.
• What changed: wrapped tool execution phase and per-run agent event callbacks in best-effort guards that log warning failures without interrupting tool processing.
• What did NOT change (scope boundary): global agent event emission, tool execution semantics, and result payload shaping are unchanged.

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 #
• Related #
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: tool-start progress callbacks can no longer crash or interfere with tool event handling when they throw or reject.
• Real environment tested: local macOS OpenClaw checkout, Node 22.19.0, running this PR branch at commit 65de17d9e09cabf804eca4050943f34e35ff2166.
• Exact steps or command run after this patch:
  • git rev-parse HEAD
  • node --import tsx --input-type=module <<'NODE' ...runtime callback proof script... NODE
  • node scripts/run-vitest.mjs src/agents/embedded-agent-subscribe.handlers.tools.test.ts -- --run
  • node_modules/.bin/oxlint --tsconfig config/tsconfig/oxlint.core.json src/agents/embedded-agent-subscribe.handlers.tools.ts
  • node_modules/.bin/oxlint --tsconfig config/tsconfig/oxlint.core.json src ui packages
  • git diff --check
• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output):

$ git rev-parse HEAD
65de17d9e09cabf804eca4050943f34e35ff2166

$ node --import tsx --input-type=module <<'NODE' ...runtime callback proof script... NODE
OpenClaw runtime callback proof
head: 65de17d9e09cabf804eca4050943f34e35ff2166
production import: src/agents/embedded-agent-subscribe.handlers.tools.ts
sync throw probe:
  tool metadata recorded: true
  item starts recorded: 2
  active items: command:tool-sync-throw, tool:tool-sync-throw
  warnings captured: 4
  warning kinds: execution-phase, agent-event, agent-event, agent-event
async rejection probe:
  tool metadata recorded: true
  item starts recorded: 2
  active items: command:tool-async-reject, tool:tool-async-reject
  warnings captured: 3
  warning kinds: agent-event, agent-event, agent-event
unhandled rejections observed: 0

$ node scripts/run-vitest.mjs src/agents/embedded-agent-subscribe.handlers.tools.test.ts -- --run
[test] starting test/vitest/vitest.agents.config.ts

 RUN  v4.1.7 /Users/xuyi/Projects/openclaw


 Test Files  1 passed (1)
      Tests  49 passed (49)
   Start at  12:23:21
   Duration  997ms (transform 403ms, setup 86ms, import 475ms, tests 372ms, environment 0ms)

[test] passed 1 Vitest shard in 3.82s

$ node_modules/.bin/oxlint --tsconfig config/tsconfig/oxlint.core.json src/agents/embedded-agent-subscribe.handlers.tools.ts
# no output; exit 0

$ node_modules/.bin/oxlint --tsconfig config/tsconfig/oxlint.core.json src ui packages
# no output; exit 0

$ git diff --check
# no output; exit 0

• Observed result after fix: the current PR head directly imported the production tool-start handler and exercised a runtime callback boundary with a synchronous execution-phase throw, synchronous per-run agent-event throws, and asynchronous per-run agent-event rejections. Tool metadata and item starts were still recorded in both probes, warning-only callback failures were captured, and zero unhandled rejections were observed. The focused Vitest and static checks also pass on the same current head.
• What was not tested: a live model/provider turn through a real chat channel. The runtime proof directly exercises the production tool-start event boundary changed by this patch.
• Before evidence (optional but encouraged): current main directly invokes the same per-run callbacks with ctx.params.onExecutionPhase?.(...) and void ctx.params.onAgentEvent?.(...), so sync throws can escape and async rejections are not observed on that path. The proof above demonstrates the current PR head converts those callback failures into warning-only observer failures while preserving tool event handling.

Root Cause (if applicable)

• Root cause: per-run progress callbacks were treated as best-effort with void, but synchronous throws still escaped and promise rejections were not caught.
• Missing detection / guardrail: no regression covered throwing or rejecting tool-start progress callbacks.
• Contributing context (if known): global agent-event listeners already guard synchronous listener failures, but the per-run callback path used by tool progress did not share that protection.

Regression Test Plan (if applicable)

• 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/agents/pi-embedded-subscribe.handlers.tools.test.ts
• Scenario the test should lock in: tool-start processing continues when progress callbacks throw or reject.
• Why this is the smallest reliable guardrail: the bug is in the tool event handler boundary itself.
• Existing test that already covers this (if any): N/A
• If no new test is added, why not: N/A

User-visible / Behavior Changes

None.

Diagram (if applicable)

Before:
[tool_start] -> [progress callback throws/rejects] -> [handler abort or unhandled rejection]

After:
[tool_start] -> [progress callback throws/rejects] -> [warning logged] -> [tool event handling continues]

Security Impact (required)

• 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
• Runtime/container: Node 22.19.0, local OpenClaw checkout
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): N/A

Steps

1. Confirm the current PR head: git rev-parse HEAD.
2. Run a runtime probe that imports src/agents/embedded-agent-subscribe.handlers.tools.ts and exercises sync-throwing plus async-rejecting progress callbacks against handleToolExecutionStart.
3. Run the focused production-handler regression suite: node scripts/run-vitest.mjs src/agents/embedded-agent-subscribe.handlers.tools.test.ts -- --run.
4. Run focused static validation:
   • node_modules/.bin/oxlint --tsconfig config/tsconfig/oxlint.core.json src/agents/embedded-agent-subscribe.handlers.tools.ts
   • node_modules/.bin/oxlint --tsconfig config/tsconfig/oxlint.core.json src ui packages
   • git diff --check

Expected

• Tool-start handling records tool metadata and item events even when progress callbacks throw or reject.
• Callback failures are logged as warnings.
• No unhandled rejection is leaked from the async callback path.
• Static checks accept the thenable-safe async guard.

Actual

• Matches expected on current PR head 65de17d9e09cabf804eca4050943f34e35ff2166.

Evidence

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

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: local OpenClaw runtime at 65de17d9e09cabf804eca4050943f34e35ff2166, production handler import, sync execution-phase callback throw, sync per-run agent-event callback throw, async per-run agent-event callback rejection, existing tool event behavior, and the thenable-safe Promise.resolve(result).catch(...) guard.
• Edge cases checked: promise rejection guard path, warning-only callback failure path, zero observed unhandled rejections, and static lint coverage for the touched handler.
• What you did not verify: live provider/gateway turn through a real chat 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: callback failures are now warning-only in this observer path.
  • Mitigation: these callbacks are progress/telemetry observers; core tool event emission and state tracking still proceed.