PR #67508: fix(agents): prefer target agent's bound Matrix account for subagent spawns

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

Description (problem / solution / changelog)

Summary

Fixes Matrix (and other-channel) subagent spawns inheriting the caller's accountId instead of the target agent's bound account, and hardens resolveFirstBoundAccountId with kind-aware multi-tier matching for peer bindings.

• src/agents/subagent-spawn.ts: adds resolveRequesterOriginForChild(...) that prefers the target agent's bound account via resolveFirstBoundAccountId({ cfg, channelId, agentId: targetAgentId, peerId, peerKind }) before falling back to the caller's accountId. Same-agent spawns short-circuit the lookup and preserve the caller's account. A new extractRequesterPeer helper peels known delivery-target prefixes (<channel>: namespace, then a generic <word>: loop) from agentTo to produce the raw peer id and — for channels whose plugin does not implement inferTargetChatType — infer peerKind from kind-prefixes (room:/channel:/chat: → channel, group:/team: → group, user:/dm:/pm: → direct) and id-embedded markers (Matrix !/@, IRC #). Id-embedded kind markers take precedence over prefix-derived kind so wrappers like room:@user:server classify correctly.
• src/routing/bound-account-read.ts: resolveFirstBoundAccountId now accepts optional peerId and peerKind, and uses a four-tier precedence model:
  1. Exact peer id match (with kind cross-check when both sides declare one) wins immediately.
  2. Wildcard peer (peer.id: "*") match — only when the caller supplies a peer AND both sides declare a matching kind (treating group/channel as equivalent, mirroring peerKindMatches in resolve-route.ts).
  3. Channel-only binding (no peer) as the default fallback.
  4. Peerless last-resort fallback (first peer-specific or wildcard binding found) for callers that pass no peerId — preserves the pre-existing first-match semantics for cron delivery resolution.
• Existing cron delivery-target.ts caller is unaffected: it still passes no peerId/peerKind, and the helper returns the same binding it would have before on realistic configs.

Why

A Matrix-bound parent session spawning a child for another agent could seed deliveryContext.accountId with the caller's account before target bindings were consulted. A child intended to post as the target agent's bound identity could end up posting as the caller — broken speaker identity in shared rooms, nondeterministic debugging, and wrong attribution in multi-agent deployments.

The original resolveFirstBoundAccountId also matched only on channel + agent, so multi-room-bound agents with different accounts per room got "first binding wins" regardless of active room. The peer-id/peer-kind aware matching fixes that while staying backward-compatible for callers that don't pass a peer (cron).

Regression coverage

Twelve unit tests in src/routing/bound-account-read.test.ts (new file) exercise the four-tier lookup: exact peer match, wildcard peer beats channel-only (with caller kind), channel-only beats wildcard (no caller kind), peer-specific fallback for peerless callers, non-matching peer skipped, channel mismatch, kind filtering, kind-unknown wildcard skip, exact id with unknown kind, group/channel equivalence, and the agent-on-different-channel no-match case.

Fifteen lifecycle tests in src/agents/openclaw-tools.subagents.sessions-spawn.lifecycle.test.ts (eleven new):

1. Matrix room-bound route uses the target agent's bound account over the caller's.
2. Peer-specific binding wins over channel-only binding for the same agent.
3. Non-matching peer falls back to the channel-only binding.
4. Wildcard peer binding matches any peer and beats channel-only.
5. Exact peer binding wins over a wildcard peer binding.
6. Same-agent subagent spawn preserves the caller's account (no re-resolution).
7. Channel-side prefixes stripped from agentTo before lookup (Matrix room:<id>).
8. <channel>:<kind>:<id> targets peel both prefixes (LINE line:group:<id>) and pick the group-kinded binding over a conflicting direct-kinded wildcard.
9. conversation:<id> prefix stripped for Teams-style targets.
10. Matrix room:@user:server classified as direct, not channel, so direct-peer bindings match.

Validation

• pnpm build ✓
• pnpm check ✓ (typecheck, lint, import cycles, boundary checks)
• pnpm test:changed ✓ (3777 passed on round 1)
• Targeted vitest across all nine rounds ✓ (27/27 on current HEAD, 12 unit + 15 lifecycle)
• Live Matrix readback on a downstream deployment (original round-1 fix): five bound target agents posted from their correct sender identities after rebuilt runtime.

Review iterations

This PR went through eight rounds of bot review (Codex + Greptile) before final approval. Commit history reflects each iteration:

Final state: all twelve bot review threads resolved, Codex Didn't find any major issues on the current HEAD.

AI-assisted

Authored with Claude Code (Claude Opus 4.6, 1M-context). Fully tested locally. I've reviewed the change and understand what it does.

Related / prior art

• #54479 (open, adjacent): seeds subagent deliveryContext from spawn params at the gateway layer — complementary, different layer.
• #51523 (open, adjacent): Matrix ACP room-binding subagent hooks — complementary.
• #28399 (closed, prior art): Matrix accountId forwarding in sendMessage.
• #58228, #60634 (closed, prior art): analogous Feishu fixes for the same bug class on another channel.

Known-red CI

• Install Smoke is red due to a pre-existing build-system gap (build:docker in package.json doesn't run scripts/write-npm-update-compat-sidecars.ts, unlike build-all.mjs). Root cause documented in #issuecomment-4261219649 with a proposed one-line fix — happy to include here or split out per maintainer preference.
• Run the GPT-5.4 / Opus 4.6 parity gate against the qa-lab mock is red and looks unrelated to this PR.

Changed files

• CHANGELOG.md (modified, +1/-0)
• extensions/discord/src/monitor/agent-components.ts (modified, +1/-0)
• extensions/discord/src/monitor/message-handler.preflight.ts (modified, +1/-0)
• extensions/discord/src/monitor/message-handler.preflight.types.ts (modified, +1/-0)
• extensions/discord/src/monitor/message-handler.process.ts (modified, +2/-0)
• extensions/discord/src/monitor/native-command-context.test.ts (modified, +3/-0)
• extensions/discord/src/monitor/native-command-context.ts (modified, +6/-0)
• extensions/discord/src/monitor/native-command.ts (modified, +2/-0)
• extensions/msteams/src/monitor-handler/message-handler.authz.test.ts (modified, +1/-0)
• extensions/msteams/src/monitor-handler/message-handler.ts (modified, +1/-0)
• extensions/slack/src/monitor/message-handler/prepare.test.ts (modified, +1/-0)
• extensions/slack/src/monitor/message-handler/prepare.ts (modified, +1/-0)
• extensions/slack/src/monitor/slash.test.ts (modified, +2/-1)
• extensions/slack/src/monitor/slash.ts (modified, +1/-0)
• src/agents/acp-spawn.test.ts (modified, +110/-0)
• src/agents/acp-spawn.ts (modified, +32/-21)
• src/agents/openclaw-tools.subagents.sessions-spawn.lifecycle.test.ts (modified, +393/-0)
• src/agents/openclaw-tools.ts (modified, +1/-0)
• src/agents/pi-embedded-runner/run.ts (modified, +1/-0)
• src/agents/pi-embedded-runner/run/attempt.ts (modified, +1/-0)
• src/agents/pi-embedded-runner/run/params.ts (modified, +2/-0)
• src/agents/pi-tools.ts (modified, +3/-0)
• src/agents/spawn-requester-origin.test.ts (added, +201/-0)
• src/agents/spawn-requester-origin.ts (added, +117/-0)
• src/agents/spawned-context.ts (modified, +1/-0)
• src/agents/subagent-spawn.test.ts (modified, +7/-10)
• src/agents/subagent-spawn.thread-binding.test.ts (modified, +111/-0)
• src/agents/subagent-spawn.ts (modified, +14/-7)
• src/agents/tools/sessions-spawn-tool.ts (modified, +3/-0)
• src/auto-reply/reply/agent-runner-utils.test.ts (modified, +2/-0)
• src/auto-reply/reply/agent-runner-utils.ts (modified, +10/-0)
• src/auto-reply/templating.ts (modified, +2/-0)
• src/cron/isolated-agent/delivery-target.test.ts (modified, +44/-0)
• src/routing/binding-scope.ts (added, +59/-0)
• src/routing/bound-account-read.test.ts (added, +485/-0)
• src/routing/bound-account-read.ts (modified, +102/-4)
• src/routing/peer-kind-match.ts (added, +11/-0)
• src/routing/resolve-route.ts (modified, +9/-31)