fix(agents): prefer target agent's bound Matrix account for subagent spawns by lukeboyett · Pull Request #67508 · openclaw/openclaw

lukeboyett · 2026-04-16T04:30:15Z

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):

Matrix room-bound route uses the target agent's bound account over the caller's.
Peer-specific binding wins over channel-only binding for the same agent.
Non-matching peer falls back to the channel-only binding.
Wildcard peer binding matches any peer and beats channel-only.
Exact peer binding wins over a wildcard peer binding.
Same-agent subagent spawn preserves the caller's account (no re-resolution).
Channel-side prefixes stripped from agentTo before lookup (Matrix room:<id>).
<channel>:<kind>:<id> targets peel both prefixes (LINE line:group:<id>) and pick the group-kinded binding over a conflicting direct-kinded wildcard.
conversation:<id> prefix stripped for Teams-style targets.
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:

Commit	Addressed
`5d11d7bb1e`	Initial fix (Matrix bound-account propagation)
`5d0027479e`	Codex P1: wildcard `*` treated as literal → three-tier precedence
`00b393064c`	Codex+Greptile P1s: same-agent spawn preserve caller; peerless wildcard; peerless peer-specific fallback
`f8430fd70b`	Codex P1: drop `peer.kind` → kind-aware matching + plugin inference
`d662dc529b`	Codex P1: unnormalized delivery-target prefixes → `normalizeRequesterPeerId`
`3f673354a4`	Three findings: LINE `<channel>:<kind>:<id>` parsing; peerless wildcard fallback restored; `group`/`channel` kind equivalence
`173827d6a9`	Codex P1: Teams `conversation:<id>` → generic `^[a-z][a-z0-9_-]*:` peeler
`249b292111`	Codex P1: id-embedded kind markers override prefix-derived kind (Matrix `room:@user` → direct)

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

fix(gateway): seed subagent session deliveryContext from spawn request params #54479 (open, adjacent): seeds subagent deliveryContext from spawn params at the gateway layer — complementary, different layer.
feat(matrix): add subagent hooks for ACP room-binding #51523 (open, adjacent): Matrix ACP room-binding subagent hooks — complementary.
fix(matrix): fix accountId not forwarded in sendMessage tool action #28399 (closed, prior art): Matrix accountId forwarding in sendMessage.
fix(feishu): resolve correct accountId for subagent group replies #58228, fix(feishu): resolve correct accountId for subagent group replies #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 this comment 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.

greptile-apps · 2026-04-16T04:33:53Z

Greptile Summary

This PR fixes a bug where Matrix (and other-channel) subagent spawns inherited the caller's accountId instead of the target agent's bound account. It adds resolveRequesterOriginForChild in subagent-spawn.ts to look up the target agent's binding before falling back to the caller's account, and extends resolveFirstBoundAccountId in bound-account-read.ts with a four-tier peer-aware precedence model (exact peer → kind-matched wildcard → channel-only → peerless fallback). Both the algorithm and its edge-case handling are well reasoned. The previous reviewer concern about peerless callers regressing to undefined (cron delivery) is correctly addressed via peerlessPeerSpecificFallback.

Confidence Score: 5/5

Safe to merge — no P0 or P1 issues found; the bug fix is correct and comprehensively tested.

The four-tier precedence model in resolveFirstBoundAccountId is correctly implemented and backward-compatible with peerless cron callers. The prefix-peeling logic in extractRequesterPeer handles all documented delivery-target formats. The same-agent short-circuit and the fallback chain are sound. All previous reviewer concerns are addressed. Twenty-seven tests pass and the implementation was validated against a live Matrix deployment.

No files require special attention.

_{Reviews (2): Last reviewed commit: "fix(agents): let id-embedded kind marker..." | Re-trigger Greptile}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7a0506b007

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

lukeboyett · 2026-04-16T09:48:32Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 00b393064c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

lukeboyett · 2026-04-16T10:13:13Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f8430fd70b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

lukeboyett · 2026-04-16T11:06:23Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d662dc529b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f3d8c0f635

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

lukeboyett · 2026-04-16T13:07:15Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f3d8c0f635

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3f673354a4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

lukeboyett · 2026-04-16T13:37:32Z

@codex review

chatgpt-codex-connector · 2026-04-16T13:43:53Z

Codex Review: Didn't find any major issues. 👍

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

lukeboyett · 2026-04-16T13:44:36Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 173827d6a9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

lukeboyett · 2026-04-16T14:56:02Z

@codex review

lukeboyett · 2026-04-16T15:18:04Z

Install Smoke root cause identified — pre-existing build-system gap, not from this PR.

dist/extensions/qa-channel/runtime-api.js is a hardcoded 109-byte compat stub produced by scripts/write-npm-update-compat-sidecars.ts. That step is listed in scripts/build-all.mjs (run by pnpm build) but is missing from the build:docker script in package.json (run by the CI Dockerfile). I verified by running the script directly — the file comes right back with the exact expected contents.

Why it surfaced here and not elsewhere: most recent main runs of the Install Smoke workflow have "conclusion":"skipped" — the preflight gates on changed-path scope and doesn't trigger install-smoke on typical commits. The files touched by this PR happen to fall in the smoke scope, so it actually executed and hit the longstanding gap. (Earlier hypothesis that our getChannelPlugin import in src/agents/subagent-spawn.ts caused this — retracted. The correlation with commit d662dc529b was coincidence: that commit is simply where the Dockerfile layer cache got invalidated and a fresh build:docker had to run, exposing the gap.)

Proposed one-line fix for package.json:

-    "build:docker": "node scripts/tsdown-build.mjs && node scripts/runtime-postbuild.mjs && node scripts/build-stamp.mjs && …",
+    "build:docker": "node scripts/tsdown-build.mjs && node scripts/runtime-postbuild.mjs && node --import tsx scripts/write-npm-update-compat-sidecars.ts && node scripts/build-stamp.mjs && …",

(Insert scripts/write-npm-update-compat-sidecars.ts between runtime-postbuild and build-stamp, matching the order in build-all.mjs.)

Happy to include that fix in this PR if you'd like — it's pure build-script, trivially reviewable, and gets Install Smoke green. Otherwise I'll leave this PR focused on the routing fix and file the build gap separately. Your call.

The CI Run the GPT-5.4 / Opus 4.6 parity gate against the qa-lab mock failure still looks unrelated to this PR.

lukeboyett · 2026-04-16T15:26:05Z

@codex review

chatgpt-codex-connector · 2026-04-16T15:33:03Z

Codex Review: Didn't find any major issues. Chef's kiss.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

gumadeiras · 2026-04-18T18:02:57Z

Merged via squash.

Prepared head SHA: 9300111038b242f6ea870fab8f5c323dbf0d456b
Merge commit: c39314c14aaab6dacee6167e974a16ee058b985e

Thanks @lukeboyett!

@gumadeiras

…spawns (openclaw#67508) Merged via squash. Prepared head SHA: 9300111 Co-authored-by: lukeboyett <46942646+lukeboyett@users.noreply.github.com> Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com> Reviewed-by: @gumadeiras

@gumadeiras

…spawns (openclaw#67508) Merged via squash. Prepared head SHA: 9300111 Co-authored-by: lukeboyett <46942646+lukeboyett@users.noreply.github.com> Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com> Reviewed-by: @gumadeiras

@gumadeiras

…spawns (openclaw#67508) Merged via squash. Prepared head SHA: 9300111 Co-authored-by: lukeboyett <46942646+lukeboyett@users.noreply.github.com> Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com> Reviewed-by: @gumadeiras

@gumadeiras

…spawns (openclaw#67508) Merged via squash. Prepared head SHA: 9300111 Co-authored-by: lukeboyett <46942646+lukeboyett@users.noreply.github.com> Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com> Reviewed-by: @gumadeiras

@gumadeiras

…spawns (openclaw#67508) Merged via squash. Prepared head SHA: 9300111 Co-authored-by: lukeboyett <46942646+lukeboyett@users.noreply.github.com> Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com> Reviewed-by: @gumadeiras

@gumadeiras

…spawns (openclaw#67508) Merged via squash. Prepared head SHA: 9300111 Co-authored-by: lukeboyett <46942646+lukeboyett@users.noreply.github.com> Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com> Reviewed-by: @gumadeiras

@gumadeiras

…spawns (openclaw#67508) Merged via squash. Prepared head SHA: 9300111 Co-authored-by: lukeboyett <46942646+lukeboyett@users.noreply.github.com> Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com> Reviewed-by: @gumadeiras

@gumadeiras

…spawns (openclaw#67508) Merged via squash. Prepared head SHA: 9300111 Co-authored-by: lukeboyett <46942646+lukeboyett@users.noreply.github.com> Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com> Reviewed-by: @gumadeiras

openclaw-barnacle Bot added agents Agent runtime and tooling size: M labels Apr 16, 2026

lukeboyett mentioned this pull request Apr 16, 2026

fix(agents): prefer target agent's bound Matrix account for subagent spawns lukeboyett/openclaw#1

Closed

greptile-apps Bot reviewed Apr 16, 2026

View reviewed changes

Comment thread src/routing/bound-account-read.ts

chatgpt-codex-connector Bot reviewed Apr 16, 2026

View reviewed changes

Comment thread src/agents/subagent-spawn.ts Outdated

Comment thread src/routing/bound-account-read.ts

openclaw-barnacle Bot added size: L and removed size: M labels Apr 16, 2026

chatgpt-codex-connector Bot reviewed Apr 16, 2026

View reviewed changes

Comment thread src/routing/bound-account-read.ts

chatgpt-codex-connector Bot reviewed Apr 16, 2026

View reviewed changes

Comment thread src/agents/subagent-spawn.ts Outdated

chatgpt-codex-connector Bot reviewed Apr 16, 2026

View reviewed changes

Comment thread src/agents/subagent-spawn.ts Outdated

Comment thread src/routing/bound-account-read.ts Outdated

chatgpt-codex-connector Bot reviewed Apr 16, 2026

View reviewed changes

Comment thread src/agents/subagent-spawn.ts Outdated

Comment thread src/routing/bound-account-read.ts Outdated

chatgpt-codex-connector Bot reviewed Apr 16, 2026

View reviewed changes

Comment thread src/routing/bound-account-read.ts Outdated

chatgpt-codex-connector Bot reviewed Apr 16, 2026

View reviewed changes

Comment thread src/agents/subagent-spawn.ts Outdated

chatgpt-codex-connector Bot reviewed Apr 16, 2026

View reviewed changes

Comment thread src/agents/subagent-spawn.ts Outdated

openclaw-barnacle Bot added size: XL and removed size: L labels Apr 16, 2026

lukeboyett marked this pull request as draft April 16, 2026 15:39

lukeboyett marked this pull request as ready for review April 16, 2026 16:34

gumadeiras added 11 commits April 18, 2026 14:01

routing: share peer-kind matching

d643e46

fix(regression): preserve peerless bound account fallback

860689c

fix(agents): preserve prefixed Teams peer ids

9c5d8e3

test(agents): cover canonical dm peer aliases

4f9460f

fix(agents): preserve plugin target kind inference

33fc14e

fix(agents): honor binding scope in child origins

8a59771

fix(agents): route requester roles into child origins

c443de6

refactor(routing): keep bound account scope generic

0b45ea9

fix(regression): propagate team scope into child spawns

91f0217

refactor(agents): clarify requester peer prefix handling

5d1fd2e

perf(routing): reuse role membership sets

9300111

gumadeiras force-pushed the fix/matrix-bound-account-subagent-spawn-squashed branch from ec114e7 to 9300111 Compare April 18, 2026 18:01

gumadeiras merged commit c39314c into openclaw:main Apr 18, 2026
9 checks passed

github-actions Bot mentioned this pull request Apr 18, 2026

📡 Upstream Digest — 2026-04-18 18:36 UTC curtismercier/openclaw-mods#609

Open

cgdusek mentioned this pull request Apr 19, 2026

fix(gateway): prefer current route delivery context #69010

Open

github-actions Bot mentioned this pull request Apr 20, 2026

🦞 OpenClaw 生态日报 2026-04-20 gsscsd/big_model_radar#215

Open

lukeboyett mentioned this pull request Apr 20, 2026

system-event-shape consumer-path leakage; propose per-event audience classification #69492

Closed

This was referenced Apr 30, 2026

[Feature]: Control UI: no cross-agent view when configuring or debugging multi-agent teams #69364

Open

Default message tool accountId to the calling agent's own Slack account when omitted #73619

Open

clawsweeper Bot mentioned this pull request May 11, 2026

Feature Request: 支持跨渠道 accountId 绑定 #54853

Open

Uh oh!

Conversation

lukeboyett commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why

Regression coverage

Validation

Review iterations

AI-assisted

Related / prior art

Known-red CI

Uh oh!

greptile-apps Bot commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

lukeboyett commented Apr 16, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

lukeboyett commented Apr 16, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

lukeboyett commented Apr 16, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

lukeboyett commented Apr 16, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

lukeboyett commented Apr 16, 2026

Uh oh!

chatgpt-codex-connector Bot commented Apr 16, 2026

Uh oh!

lukeboyett commented Apr 16, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

lukeboyett commented Apr 16, 2026

Uh oh!

lukeboyett commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

lukeboyett commented Apr 16, 2026 •

edited

Loading

greptile-apps Bot commented Apr 16, 2026 •

edited

Loading

lukeboyett commented Apr 16, 2026 •

edited

Loading