Greptile Summary

This PR fixes a three-part bug where sessionKey was not threaded into the message_sending hook context, and where session.key diverged from the agent runtime's params.sessionKey on native-command-redirect flows. The fix is additive and narrow: sessionKeyForInternalHooks is plumbed into applyMessageSendingHook, dispatch-from-config.ts mirrors get-reply.ts's targetSessionKey || ctx.SessionKey resolution, and JSDoc tightens the invariant contract. Three new tests directly validate the corrected behavior.

Confidence Score: 5/5

This PR is safe to merge — changes are additive, well-tested, and confined to narrow plumbing points.

No P0 or P1 issues found. The ?? vs || difference between dispatch-from-config.ts and get-reply.ts is semantically equivalent because normalizeOptionalString never returns an empty string (it collapses to undefined for blank/whitespace input). All three fix layers are coherent, the 56/56 test suite passes, and types are clean.

No files require special attention.

_{Reviews (2): Last reviewed commit: "fix(outbound): align session.key with ag..." | Re-trigger Greptile}

Codex review: needs real behavior proof before merge.

Summary
Review failed before ClawSweeper could summarize the requested change.

Reproducibility: unclear. The review failed before ClawSweeper could establish a reproduction path.

Real behavior proof
Not applicable: Real behavior proof was not assessed because the Codex review failed.

Next step before merge
Review did not complete, so no work-lane recommendation was made.

@greptile-apps: We have added some documentation to fully explain the hook surface contract regarding session key vs policy key. please re-review.

Round 4 — addressing Clawsweeper review feedback

Round-4 commit: 862bb66603 (force-push not used; this is a follow-up commit on top of the existing branch, per repo policy).

Each finding from the previous review is addressed individually below, followed by the after-fix real-runtime behavior proof maintainer review asked for.

[P2] Align hook docs with delivered outbound fields — src/plugins/hook-message.types.ts:19-34

Problem (paraphrased). The new JSDoc said outbound message_sending and message_sent both mirror OutboundSessionContext.key, and recommended runId for agent_end ↔ message_sending correlation. In practice this PR only threaded sessionKey into message_sending; createMessageSentEmitter still built the sent context without sessionKey or runId, and runId was not plumbed through outbound delivery at all. The contract was overstated for message_sent and outright false for runId on outbound hooks.

Solution.

1. Threaded the canonical outbound sessionKey into the message_sent hook context too. createMessageSentEmitter already takes sessionKeyForInternalHooks (the same value deliverOutboundPayloadsCore computes from params.mirror?.sessionKey ?? params.session?.key for the internal message:sent hook); the canonical context now mirrors that into the plugin context. This makes the message_sending and message_sent contracts symmetric and matches the value the internal hook fires with.
2. Narrowed the JSDoc on PluginHookMessageContext.runId to honestly describe what is plumbed today: inbound message hooks and agent-runtime hooks (agent_end, llm_input, llm_output) carry runId; outbound message_sending / message_sent do not yet, so plugins should rely on sessionKey for outbound→inbound correlation today (with the documented caveat that it cannot disambiguate concurrent turns in the same session).
3. Narrowed the JSDoc on PluginHookMessageContext.sessionKey to call out that the field is omitted when delivery has no resolvable session (e.g. internal smoke runs), matching the existing "WITHOUT session" code path.

Result. Commit 862bb66603. Validation:

$ pnpm tsgo:core
... clean

$ pnpm tsgo:core:test
... clean

$ pnpm vitest run src/infra/outbound/deliver.test.ts
 ✓ infra ../../src/infra/outbound/deliver.test.ts (64 tests) 194ms
 Test Files  1 passed (1)
      Tests  64 passed (64)

$ pnpm vitest run src/hooks/message-hook-mappers.test.ts
 ✓ hooks ../../src/hooks/message-hook-mappers.test.ts (11 tests) 23ms
 Test Files  1 passed (1)
      Tests  11 passed (11)

$ pnpm plugin-sdk:api:check
OK docs/.generated/plugin-sdk-api-baseline.sha256

Two new contract tests in src/infra/outbound/deliver.test.ts pin the message_sent sessionKey behavior so it cannot diverge from message_sending unobserved:

• threads sessionKey into the message_sent hook context when session is provided
• omits sessionKey from the message_sent hook context when session is absent

[P3] Add the hook fix to the changelog — src/infra/outbound/deliver.ts:1105

Problem (paraphrased). This PR changes user-facing plugin hook behavior and public hook/session JSDoc but did not update CHANGELOG.md. Repo policy requires user-facing fixes to be recorded under ## Unreleased.

Solution. Added a single Plugins/hooks entry under ## Unreleased → ### Changes describing both runtime changes (canonical outbound sessionKey threaded into message_sending and message_sent; native-command-redirect routed replies aligned on CommandTargetSessionKey), with the user-visible consequence (plugins correlating per-turn state across agent_end and outbound delivery hooks no longer see the session key drop on direct delivery or diverge on native redirects). Credits @zeroaltitude per the contributor template.

Result. Commit 862bb66603, single line added under ## Unreleased / ### Changes.

[P3] Cover native redirect session-key selection — src/auto-reply/reply/dispatch-from-config.ts:583-586

Problem (paraphrased). This PR changed routed native-command replies to send the redirect target session key, but the added tests only exercised direct outbound delivery. We needed a focused dispatch-from-config regression so agent_end and message_sending cannot diverge again while the new delivery tests still pass.

Solution. Added two paired regression tests in src/auto-reply/reply/dispatch-from-config.test.ts that drive dispatchReplyFromConfig with a context that triggers routing (OriginatingChannel differs from Provider) and assert on the actual routeReply call args:

1. routes native-command-redirect replies using the redirect target sessionKey for outbound delivery — CommandSource: "native", CommandTargetSessionKey: "agent:main:telegram:direct:999", SessionKey: "agent:main:slack:channel:CHAN1". Asserts routeReply is called with sessionKey: "agent:main:telegram:direct:999" and policySessionKey: "agent:main:telegram:direct:999" — i.e. routed delivery follows the redirect target, matching the agent runtime's params.sessionKey resolution.
2. routes non-native (text) command replies using the inbound sessionKey for outbound delivery — companion test with the same CommandTargetSessionKey populated but CommandSource: "text". Asserts routeReply keeps sessionKey and policySessionKey set to the inbound SessionKey. This guards against accidental generalization of the native-redirect branch into non-native command flows.

Result. Commit 862bb66603. Validation:

$ pnpm vitest run src/auto-reply/reply/dispatch-from-config.test.ts
 ✓ auto-reply ../../src/auto-reply/reply/dispatch-from-config.test.ts (105 tests) 3671ms
 Test Files  1 passed (1)
      Tests  105 passed (105)

(Was 103 before; both new tests are included in the 105.)

After-fix real OpenClaw/plugin behavior proof

Problem (paraphrased). The PR body reported unit tests and typecheck only and did not include after-fix output from a real OpenClaw / plugin run.

Solution. Committed scripts/proof-73706-message-sending-session-key.ts, a self-checking real-runtime harness that does not use vitest mocks. It wires up the production deliverOutboundPayloads path against:

• a real PluginRegistry populated with one real channel plugin (createOutboundTestPlugin with a real sendText adapter) and two real plugin hooks (message_sending, message_sent)
• the real setActivePluginRegistry channel resolution path
• the real getGlobalHookRunner() / initializeGlobalHookRunner() singleton path (no fake hook runner — same code the live gateway uses)

It then exercises three scenarios end-to-end and asserts on the actual hook ctx received at runtime. (The harness caught a pre-commit local regression where my message_sent change had been reverted by an earlier git checkout HEAD -- .; the unit test mock had been happy with stale mock state, but the real runtime path through getGlobalHookRunner exposed the missing field. So this harness is doing its job as a guard against the exact divergence Clawsweeper flagged.)

Run command and full output (copied verbatim from terminal):

$ pnpm tsx scripts/proof-73706-message-sending-session-key.ts

[proof-73706] Real-runtime behavior proof for outbound session-key threading.
[proof-73706] Production code paths: deliverOutboundPayloads + getGlobalHookRunner.

=== Scenario: outbound delivery WITH session.key (canonical key from agent runtime) ===
deliverOutboundPayloads result: [{"channel":"matrix","messageId":"mx-1778038038060","roomId":"!room:example"}]
[message_sending] ctx.sessionKey = "agent:tank:slack:channel:CHAN1"
[message_sending] full ctx     = {"channelId":"matrix","conversationId":"!room:example","sessionKey":"agent:tank:slack:channel:CHAN1"}
[message_sent] ctx.sessionKey = "agent:tank:slack:channel:CHAN1"
[message_sent] full ctx     = {"channelId":"matrix","conversationId":"!room:example","sessionKey":"agent:tank:slack:channel:CHAN1","messageId":"mx-1778038038060"}

=== Scenario: outbound delivery WITHOUT session (narrowed docs branch) ===
deliverOutboundPayloads result: [{"channel":"matrix","messageId":"mx-1778038038070","roomId":"!room:example"}]
[message_sending] ctx.sessionKey = (undefined)
[message_sending] full ctx     = {"channelId":"matrix","conversationId":"!room:example"}
[message_sent] ctx.sessionKey = (undefined)
[message_sent] full ctx     = {"channelId":"matrix","conversationId":"!room:example","messageId":"mx-1778038038070"}

=== Scenario: native-redirect: session.key = CommandTargetSessionKey (what dispatch-from-config.ts now passes) ===
deliverOutboundPayloads result: [{"channel":"matrix","messageId":"mx-1778038038072","roomId":"!room:example"}]
[message_sending] ctx.sessionKey = "agent:tank:telegram:direct:999"
[message_sending] full ctx     = {"channelId":"matrix","conversationId":"!room:example","sessionKey":"agent:tank:telegram:direct:999"}
[message_sent] ctx.sessionKey = "agent:tank:telegram:direct:999"
[message_sent] full ctx     = {"channelId":"matrix","conversationId":"!room:example","sessionKey":"agent:tank:telegram:direct:999","messageId":"mx-1778038038072"}

[proof-73706] All runtime assertions passed.

What this proof demonstrates against the real runtime (not mocks):

• Scenario 1 (direct delivery, session present): Both message_sending and message_sent receive ctx.sessionKey === "agent:tank:slack:channel:CHAN1" — the canonical OutboundSessionContext.key value plugins observing agent_end will see for the same turn.
• Scenario 2 (no session attached): Both hooks omit sessionKey, exercising the narrowed docs branch ("plugins must treat it as optional"). No accidental fallback, no policyKey leakage.
• Scenario 3 (native redirect target): When dispatch-from-config.ts resolves agentRuntimeSessionKey = CommandTargetSessionKey ?? SessionKey for CommandSource: "native" and forwards it via routeReply (which lands in deliverOutboundPayloads as session.key), both outbound hooks observe the redirect-target session — proving end-to-end that agent_end (fired with the runtime sessionKey) and the outbound hooks now see the same canonical key on native redirects.

The harness is committed at scripts/proof-73706-message-sending-session-key.ts so reviewers and CI can re-run it; it asserts each ctx.sessionKey value and exits non-zero on any regression.

Full validation gate (Round 4)

pnpm tsgo:core                                                      → clean
pnpm tsgo:core:test                                                 → clean
pnpm vitest run src/infra/outbound/deliver.test.ts                  → 64/64 passed
pnpm vitest run src/auto-reply/reply/dispatch-from-config.test.ts   → 105/105 passed
pnpm vitest run src/hooks/message-hook-mappers.test.ts              → 11/11 passed
pnpm oxlint <touched files>                                         → 0 warnings, 0 errors
pnpm plugin-sdk:api:check                                           → OK
git diff --check                                                    → clean
pnpm tsx scripts/proof-73706-message-sending-session-key.ts         → all 3 runtime assertions pass

Ready for re-review.

@clawsweeper please re-review. Round 4 follow-up commit 862bb66603 addressed all findings: (1) Threaded canonical sessionKey into message_sent hook context symmetrically with message_sending; (2) Narrowed JSDoc on runId to honestly reflect inbound-only plumbing today; (3) Narrowed JSDoc on sessionKey to note omission on internal smoke runs; (4) Added two new pinned contract tests for message_sent sessionKey; (5) Added CHANGELOG entry; (6) Added two dispatch-from-config regression tests covering native vs. non-native session-key routing. Real-runtime proof updated in prior comment, all 3 scenarios verified against production hook runner (no mocks).