Summary

• Problem: When a background exec command (exec background=true) completes, the agent receives a heartbeat wake with [OpenClaw heartbeat poll] as the transcript placeholder. This causes the model to treat the turn as a heartbeat poll — it reads HEARTBEAT.md and either runs periodic tasks or replies HEARTBEAT_OK, ignoring the exec completion details.
• Why now: Background exec is the primary async mechanism for long-running shell commands. The completion notification was effectively invisible to the model, defeating the purpose of async exec.
• Outcome:
  • Exec completion events now use a dedicated [OpenClaw exec completion] transcript placeholder with the exec details appended in the message body, making them visible to both the model and before_agent_run security plugins.
  • When deliverToUser is false, buildExecEventPrompt now shows exec output with "Handle the result internally. Continue the task based on the result if needed" instead of "HEARTBEAT_OK only" — so the model sees completion details in any active conversation without overriding delivery authorization.
• Intentionally out of scope: Non-exec heartbeat behavior is unchanged.
• Success: The model now responds to exec completion with the command output (e.g. "The background command has finished. Here's the output:\n\nfirst done\n\n✅ Completed successfully (exit code 0)") instead of reading HEARTBEAT.md and replying HEARTBEAT_OK.
• Reviewer focus:
  • Security gate visibility: exec details are in the message body ([OpenClaw exec completion]\n\n...), not in a separate custom_message, so before_agent_run hooks and security plugins can inspect the full content.
  • The isExecCompletionUserMessage filter uses startsWith("EXEC_COMPLETION_TRANSCRIPT_PROMPT\n") to handle the new body format.
  • deliverToUser is params.canRelayToUser only — no override. Instead, buildExecEventPrompt's !deliverToUser branch now shows exec output with "handle internally, continue task" instructions.
  • The lastChannel parameter has been removed from resolveHeartbeatRunPrompt.

Linked context

No related issue directly — discovered while investigating exec background completion notification behavior.

Related:

• The existing HEARTBEAT_TRANSCRIPT_PROMPT ("[OpenClaw heartbeat poll]") pattern established the transcript placeholder filtering mechanism that this PR extends for exec completions.

ClawSweeper feedback addressed

P1/P2: Preserve internal-only exec delivery

The original P1 finding flagged hard-coding deliverToUser: true as bypassing the target: "none" delivery contract. Subsequent reviews flagged that raw lastChannel should not override delivery authorization. This PR addresses both concerns by separating exec event visibility from delivery authorization within buildExecEventPrompt:

deliverToUser stays tied to canonical delivery:

deliverToUser: params.canRelayToUser — no override. The lastChannel parameter has been removed from resolveHeartbeatRunPrompt. For webchat (where canRelayToUser is false because there's no to address), deliverToUser is false.

Exec output is visible regardless of deliverToUser:

When deliverToUser is false, buildExecEventPrompt no longer says "reply HEARTBEAT_OK only" or "do not mention, summarize, or reuse command output." Instead, it includes the completion details with output and instructs the model to "Handle the result internally. Continue the task based on the result if needed." This way:

• The model sees exec output in the active conversation and can respond naturally
• No deliverToUser override is needed
• Explicit target: "none" is naturally respected (deliverToUser stays false, no special check needed)
• Non-webchat channels with target: "none" also get the same improved prompt

Why this approach:

canRelayToUser checks whether the delivery system can actively push a message through the channel's addressing system (requires both channel and to). Background exec completion in an active webchat session is a different scenario — the message doesn't need external delivery; the model is already in the conversation and just needs to see the result. Rather than overriding deliverToUser to bypass this distinction, the prompt itself is adapted to show context without instructing relay.

Security gate visibility:

Unlike PR #91817 (which was closed because before_agent_run security plugins couldn't see exec details hidden in custom_message), this PR puts exec details directly in the message body via transcriptBody = "${EXEC_COMPLETION_TRANSCRIPT_PROMPT}\n\n${effectiveBaseBody}". Security plugins inspecting user messages will see [OpenClaw exec completion]\n\nExec completed (...) — the full content the model receives, not just a placeholder.

Why exec details persist in transcriptBody:

Background exec is transparent to the user — the command runs asynchronously and completes without the user's direct involvement. When it finishes, the result needs to be visible in the ongoing conversation so the user can see what happened and the model can reference it in follow-up turns. An ephemeral-only design (visible on the current turn then discarded) would mean:

• The user could never scroll back to see what a background command produced
• The model would lose context of completed work after a single turn
• Debugging failed background commands would require external logs

The [OpenClaw exec completion] marker makes these entries distinguishable from regular user messages, and the existing filterHeartbeatTranscriptArtifacts mechanism already handles cleanup — it only retains the entry when the model's response is substantive (i.e., the model actually used the exec result). This is intentional: if the model responded to the exec output, that context is relevant for future turns. The same design principle applies to regular command output — it becomes part of the conversation history.

Real behavior proof

• Behavior or issue addressed: Background exec completion notification reaches the model as a heartbeat poll, causing the model to ignore exec output and run heartbeat tasks instead.

• Real environment tested: Local gateway with a Qwen3 family model, behind an OpenAI-compatible proxy that logs all LLM requests/responses.

• Exact steps or command run after this patch: Ran exec background=true command="sleep 10 && echo 'first done'", waited ~10 seconds for the exec completion wake, then inspected the proxy logs.

• Evidence after fix:

  User message body sent to the model (exec details inline, visible to security plugins):

  [user]: [OpenClaw exec completion]
  
  An async command you ran earlier has completed. The completion details are:
  
  Exec completed (tide-orb, code 0) :: first done
  
  User delivery is disabled for this run. Handle the result internally. Continue the task based on the result if needed.
  

  Model response:

  The background command has completed successfully.
  
  **Result:**
  - Exit code: 0
  - Output: `first done`
  

• Before evidence:

  Last user message (shows [OpenClaw heartbeat poll] instead of exec details):

  [user]: [Wed 2026-06-10 17:18 GMT+8] [OpenClaw heartbeat poll]
  

  Model response: HEARTBEAT_OK (model treated it as a heartbeat poll, ignored exec completion)

• Observed result after fix: The [OpenClaw exec completion] placeholder prevents the heartbeat behavior. The model sees the exec output in the runtime context and responds appropriately with the command results.

• What was not tested: Multi-line exec output, failed commands (non-zero exit), long-running commands with partial output.

• Proof limitations: Evidence is from an intercepted LLM request log, not from OpenClaw gateway logs directly. The streaming output was reconstructed from SSE chunks.

Patch surface

Tests and validation

• pnpm test src/auto-reply/heartbeat-filter.test.ts: All tests pass.
• pnpm test src/auto-reply/reply/prompt-prelude.test.ts: All tests pass.
• pnpm test src/infra/heartbeat-runner.ghost-reminder.test.ts: All tests pass.
• Added test for isExecCompletionUserMessage with exec details appended in body.
• Added test for isHeartbeatUserMessage with EXEC_COMPLETION_TRANSCRIPT_PROMPT returns true.
• Added test for filterHeartbeatTranscriptArtifacts removing exec completion pairs alongside heartbeat pairs.
• Added test for buildReplyPromptEnvelope with exec-event Provider: transcriptCommandBody includes exec details.
• Also ran live gateway test (described in Real behavior proof above) with proxy logging to verify the fix works end-to-end.

Risk checklist

• Did user-visible behavior change? Yes — exec completion notifications now properly reach the model's attention instead of being treated as heartbeat polls.
• Did config, environment, or migration behavior change? No
• Did security, auth, secrets, network, or tool execution behavior change? No
• What is the highest-risk area? The transcript filter must correctly identify exec completion messages. The filter now uses startsWith instead of exact match, which is correct since exec details are appended after the marker.
• How is that risk mitigated? The filter checks for the EXEC_COMPLETION_TRANSCRIPT_PROMPT prefix with a newline separator before any exec details. Unit tests cover both the bare marker and marker-with-details formats.

Current review state

• Next action: Author ready for review.
• Waiting on: None.
• Comments addressed: P1 (delivery override) — scoped to exec events + webchat; security gate visibility — exec details now in message body, not hidden in custom_message.