feat: thread-bound subagents on Discord by onutc · Pull Request #21805 · openclaw/openclaw

onutc · 2026-02-20T11:58:00Z

Sub-agents spawned via sessions_spawn can now automatically get their own Discord thread. Messages from the sub-agent are routed to the thread, and user messages in the thread go back to that sub-agent's session.

thread: true creates the thread on spawn. mode: "run" closes the thread when the task finishes. mode: "session" keeps it open for follow-up conversation. Bindings persist across restarts and clean up automatically on kill/unfocus.

Added sessions_spawn support for thread and mode (run | session).
Implemented persistent subagent session mode (mode: "session") for thread-bound workflows.
Added lifecycle hook flow for spawning/spawned/ended and wired Discord plugin hooks to:
- auto-bind spawned subagents to threads (when enabled),
- resolve delivery targets to bound threads,
- unbind on end/reset/delete.
Implemented Discord thread binding manager stack (state, lifecycle, Discord API integration, TTL sweeper, persistence).
Added /focus, /unfocus, /agents, and /session ttl support for thread-bound session operations.
Added TTL intro/farewell messaging and TTL-expiry unbind behavior.

config toggles

session.threadBindings.ttlHours
- Global default TTL for thread-bound sessions across channels.
- Default: 24 hours. 0 disables TTL.
channels.discord.threadBindings.ttlHours
- Discord-specific TTL override.
- Default: inherits session.threadBindings.ttlHours (or 24 if unset). 0 disables TTL.
channels.discord.threadBindings.spawnSubagentSessions
- Enables sessions_spawn({ thread: true }) auto-create+bind behavior for Discord.
- Default: false (feature is opt-in).
Related (subagent behavior touched in this PR): agents.defaults.subagents.maxSpawnDepth
- Default is now 1 unless explicitly configured.

Routing and lifecycle fixes

Bound thread messages now bypass mention-gating correctly and route to the bound session.
Outbound replies for bound sessions route to thread targets (including webhook persona path).
Thread binding records are scoped by account + thread (multi-account safe).
Spawn failure cleanup now deletes provisional child sessions and avoids stale bindings.
Prevented duplicate subagent_ended emissions on internal cleanup deletes via controlled lifecycle emission.

Additional improvements

Centralized session transcript file resolution/persistence via shared helper.
Split large modules for maintainability:
- commands-subagents into per-action handlers,
- provider allowlist and gateway lifecycle into dedicated modules,
- subagent cleanup decision logic into pure helper module.

Testing

Added/updated unit + e2e coverage across spawn hooks, thread bindings, preflight routing, reply delivery, session lifecycle, and
command flows.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6985179156

ℹ️ 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".

greptile-apps

_{58 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

chatgpt-codex-connector · 2026-02-21T09:40:52Z

To use Codex here, create a Codex account and connect to github.

@onutc

* docs: thread-bound subagents plan * docs: add exact thread-bound subagent implementation touchpoints * Docs: prioritize auto thread-bound subagent flow * Docs: add ACP harness thread-binding extensions * Discord: add thread-bound session routing and auto-bind spawn flow * Subagents: add focus commands and ACP/session binding lifecycle hooks * Tests: cover thread bindings, focus commands, and ACP unbind hooks * Docs: add plugin-hook appendix for thread-bound subagents * Plugins: add subagent lifecycle hook events * Core: emit subagent lifecycle hooks and decouple Discord bindings * Discord: handle subagent bind lifecycle via plugin hooks * Subagents: unify completion finalizer and split registry modules * Add subagent lifecycle events module * Hooks: fix subagent ended context key * Discord: share thread bindings across ESM and Jiti * Subagents: add persistent sessions_spawn mode for thread-bound sessions * Subagents: clarify thread intro and persistent completion copy * test(subagents): stabilize sessions_spawn lifecycle cleanup assertions * Discord: add thread-bound session TTL with auto-unfocus * Subagents: fail session spawns when thread bind fails * Subagents: cover thread session failure cleanup paths * Session: add thread binding TTL config and /session ttl controls * Tests: align discord reaction expectations * Agent: persist sessionFile for keyed subagent sessions * Discord: normalize imports after conflict resolution * Sessions: centralize sessionFile resolve/persist helper * Discord: harden thread-bound subagent session routing * Rebase: resolve upstream/main conflicts * Subagents: move thread binding into hooks and split bindings modules * Docs: add channel-agnostic subagent routing hook plan * Agents: decouple subagent routing from Discord * Discord: refactor thread-bound subagent flows * Subagents: prevent duplicate end hooks and orphaned failed sessions * Refactor: split subagent command and provider phases * Subagents: honor hook delivery target overrides * Discord: add thread binding kill switches and refresh plan doc * Discord: fix thread bind channel resolution * Routing: centralize account id normalization * Discord: clean up thread bindings on startup failures * Discord: add startup cleanup regression tests * Docs: add long-term thread-bound subagent architecture * Docs: split session binding plan and dedupe thread-bound doc * Subagents: add channel-agnostic session binding routing * Subagents: stabilize announce completion routing tests * Subagents: cover multi-bound completion routing * Subagents: suppress lifecycle hooks on failed thread bind * tests: fix discord provider mock typing regressions * docs/protocol: sync slash command aliases and delete param models * fix: add changelog entry for Discord thread-bound subagents (openclaw#21805) (thanks @onutc) --------- Co-authored-by: Shadow <[email protected]>

@onutc

* docs: thread-bound subagents plan * docs: add exact thread-bound subagent implementation touchpoints * Docs: prioritize auto thread-bound subagent flow * Docs: add ACP harness thread-binding extensions * Discord: add thread-bound session routing and auto-bind spawn flow * Subagents: add focus commands and ACP/session binding lifecycle hooks * Tests: cover thread bindings, focus commands, and ACP unbind hooks * Docs: add plugin-hook appendix for thread-bound subagents * Plugins: add subagent lifecycle hook events * Core: emit subagent lifecycle hooks and decouple Discord bindings * Discord: handle subagent bind lifecycle via plugin hooks * Subagents: unify completion finalizer and split registry modules * Add subagent lifecycle events module * Hooks: fix subagent ended context key * Discord: share thread bindings across ESM and Jiti * Subagents: add persistent sessions_spawn mode for thread-bound sessions * Subagents: clarify thread intro and persistent completion copy * test(subagents): stabilize sessions_spawn lifecycle cleanup assertions * Discord: add thread-bound session TTL with auto-unfocus * Subagents: fail session spawns when thread bind fails * Subagents: cover thread session failure cleanup paths * Session: add thread binding TTL config and /session ttl controls * Tests: align discord reaction expectations * Agent: persist sessionFile for keyed subagent sessions * Discord: normalize imports after conflict resolution * Sessions: centralize sessionFile resolve/persist helper * Discord: harden thread-bound subagent session routing * Rebase: resolve upstream/main conflicts * Subagents: move thread binding into hooks and split bindings modules * Docs: add channel-agnostic subagent routing hook plan * Agents: decouple subagent routing from Discord * Discord: refactor thread-bound subagent flows * Subagents: prevent duplicate end hooks and orphaned failed sessions * Refactor: split subagent command and provider phases * Subagents: honor hook delivery target overrides * Discord: add thread binding kill switches and refresh plan doc * Discord: fix thread bind channel resolution * Routing: centralize account id normalization * Discord: clean up thread bindings on startup failures * Discord: add startup cleanup regression tests * Docs: add long-term thread-bound subagent architecture * Docs: split session binding plan and dedupe thread-bound doc * Subagents: add channel-agnostic session binding routing * Subagents: stabilize announce completion routing tests * Subagents: cover multi-bound completion routing * Subagents: suppress lifecycle hooks on failed thread bind * tests: fix discord provider mock typing regressions * docs/protocol: sync slash command aliases and delete param models * fix: add changelog entry for Discord thread-bound subagents (openclaw#21805) (thanks @onutc) --------- Co-authored-by: Shadow <[email protected]>

@onutc

* docs: thread-bound subagents plan * docs: add exact thread-bound subagent implementation touchpoints * Docs: prioritize auto thread-bound subagent flow * Docs: add ACP harness thread-binding extensions * Discord: add thread-bound session routing and auto-bind spawn flow * Subagents: add focus commands and ACP/session binding lifecycle hooks * Tests: cover thread bindings, focus commands, and ACP unbind hooks * Docs: add plugin-hook appendix for thread-bound subagents * Plugins: add subagent lifecycle hook events * Core: emit subagent lifecycle hooks and decouple Discord bindings * Discord: handle subagent bind lifecycle via plugin hooks * Subagents: unify completion finalizer and split registry modules * Add subagent lifecycle events module * Hooks: fix subagent ended context key * Discord: share thread bindings across ESM and Jiti * Subagents: add persistent sessions_spawn mode for thread-bound sessions * Subagents: clarify thread intro and persistent completion copy * test(subagents): stabilize sessions_spawn lifecycle cleanup assertions * Discord: add thread-bound session TTL with auto-unfocus * Subagents: fail session spawns when thread bind fails * Subagents: cover thread session failure cleanup paths * Session: add thread binding TTL config and /session ttl controls * Tests: align discord reaction expectations * Agent: persist sessionFile for keyed subagent sessions * Discord: normalize imports after conflict resolution * Sessions: centralize sessionFile resolve/persist helper * Discord: harden thread-bound subagent session routing * Rebase: resolve upstream/main conflicts * Subagents: move thread binding into hooks and split bindings modules * Docs: add channel-agnostic subagent routing hook plan * Agents: decouple subagent routing from Discord * Discord: refactor thread-bound subagent flows * Subagents: prevent duplicate end hooks and orphaned failed sessions * Refactor: split subagent command and provider phases * Subagents: honor hook delivery target overrides * Discord: add thread binding kill switches and refresh plan doc * Discord: fix thread bind channel resolution * Routing: centralize account id normalization * Discord: clean up thread bindings on startup failures * Discord: add startup cleanup regression tests * Docs: add long-term thread-bound subagent architecture * Docs: split session binding plan and dedupe thread-bound doc * Subagents: add channel-agnostic session binding routing * Subagents: stabilize announce completion routing tests * Subagents: cover multi-bound completion routing * Subagents: suppress lifecycle hooks on failed thread bind * tests: fix discord provider mock typing regressions * docs/protocol: sync slash command aliases and delete param models * fix: add changelog entry for Discord thread-bound subagents (openclaw#21805) (thanks @onutc) --------- Co-authored-by: Shadow <[email protected]>

@onutc

* docs: thread-bound subagents plan * docs: add exact thread-bound subagent implementation touchpoints * Docs: prioritize auto thread-bound subagent flow * Docs: add ACP harness thread-binding extensions * Discord: add thread-bound session routing and auto-bind spawn flow * Subagents: add focus commands and ACP/session binding lifecycle hooks * Tests: cover thread bindings, focus commands, and ACP unbind hooks * Docs: add plugin-hook appendix for thread-bound subagents * Plugins: add subagent lifecycle hook events * Core: emit subagent lifecycle hooks and decouple Discord bindings * Discord: handle subagent bind lifecycle via plugin hooks * Subagents: unify completion finalizer and split registry modules * Add subagent lifecycle events module * Hooks: fix subagent ended context key * Discord: share thread bindings across ESM and Jiti * Subagents: add persistent sessions_spawn mode for thread-bound sessions * Subagents: clarify thread intro and persistent completion copy * test(subagents): stabilize sessions_spawn lifecycle cleanup assertions * Discord: add thread-bound session TTL with auto-unfocus * Subagents: fail session spawns when thread bind fails * Subagents: cover thread session failure cleanup paths * Session: add thread binding TTL config and /session ttl controls * Tests: align discord reaction expectations * Agent: persist sessionFile for keyed subagent sessions * Discord: normalize imports after conflict resolution * Sessions: centralize sessionFile resolve/persist helper * Discord: harden thread-bound subagent session routing * Rebase: resolve upstream/main conflicts * Subagents: move thread binding into hooks and split bindings modules * Docs: add channel-agnostic subagent routing hook plan * Agents: decouple subagent routing from Discord * Discord: refactor thread-bound subagent flows * Subagents: prevent duplicate end hooks and orphaned failed sessions * Refactor: split subagent command and provider phases * Subagents: honor hook delivery target overrides * Discord: add thread binding kill switches and refresh plan doc * Discord: fix thread bind channel resolution * Routing: centralize account id normalization * Discord: clean up thread bindings on startup failures * Discord: add startup cleanup regression tests * Docs: add long-term thread-bound subagent architecture * Docs: split session binding plan and dedupe thread-bound doc * Subagents: add channel-agnostic session binding routing * Subagents: stabilize announce completion routing tests * Subagents: cover multi-bound completion routing * Subagents: suppress lifecycle hooks on failed thread bind * tests: fix discord provider mock typing regressions * docs/protocol: sync slash command aliases and delete param models * fix: add changelog entry for Discord thread-bound subagents (openclaw#21805) (thanks @onutc) --------- Co-authored-by: Shadow <[email protected]>

@onutc

* docs: thread-bound subagents plan * docs: add exact thread-bound subagent implementation touchpoints * Docs: prioritize auto thread-bound subagent flow * Docs: add ACP harness thread-binding extensions * Discord: add thread-bound session routing and auto-bind spawn flow * Subagents: add focus commands and ACP/session binding lifecycle hooks * Tests: cover thread bindings, focus commands, and ACP unbind hooks * Docs: add plugin-hook appendix for thread-bound subagents * Plugins: add subagent lifecycle hook events * Core: emit subagent lifecycle hooks and decouple Discord bindings * Discord: handle subagent bind lifecycle via plugin hooks * Subagents: unify completion finalizer and split registry modules * Add subagent lifecycle events module * Hooks: fix subagent ended context key * Discord: share thread bindings across ESM and Jiti * Subagents: add persistent sessions_spawn mode for thread-bound sessions * Subagents: clarify thread intro and persistent completion copy * test(subagents): stabilize sessions_spawn lifecycle cleanup assertions * Discord: add thread-bound session TTL with auto-unfocus * Subagents: fail session spawns when thread bind fails * Subagents: cover thread session failure cleanup paths * Session: add thread binding TTL config and /session ttl controls * Tests: align discord reaction expectations * Agent: persist sessionFile for keyed subagent sessions * Discord: normalize imports after conflict resolution * Sessions: centralize sessionFile resolve/persist helper * Discord: harden thread-bound subagent session routing * Rebase: resolve upstream/main conflicts * Subagents: move thread binding into hooks and split bindings modules * Docs: add channel-agnostic subagent routing hook plan * Agents: decouple subagent routing from Discord * Discord: refactor thread-bound subagent flows * Subagents: prevent duplicate end hooks and orphaned failed sessions * Refactor: split subagent command and provider phases * Subagents: honor hook delivery target overrides * Discord: add thread binding kill switches and refresh plan doc * Discord: fix thread bind channel resolution * Routing: centralize account id normalization * Discord: clean up thread bindings on startup failures * Discord: add startup cleanup regression tests * Docs: add long-term thread-bound subagent architecture * Docs: split session binding plan and dedupe thread-bound doc * Subagents: add channel-agnostic session binding routing * Subagents: stabilize announce completion routing tests * Subagents: cover multi-bound completion routing * Subagents: suppress lifecycle hooks on failed thread bind * tests: fix discord provider mock typing regressions * docs/protocol: sync slash command aliases and delete param models * fix: add changelog entry for Discord thread-bound subagents (openclaw#21805) (thanks @onutc) --------- Co-authored-by: Shadow <[email protected]>

@onutc

* docs: thread-bound subagents plan * docs: add exact thread-bound subagent implementation touchpoints * Docs: prioritize auto thread-bound subagent flow * Docs: add ACP harness thread-binding extensions * Discord: add thread-bound session routing and auto-bind spawn flow * Subagents: add focus commands and ACP/session binding lifecycle hooks * Tests: cover thread bindings, focus commands, and ACP unbind hooks * Docs: add plugin-hook appendix for thread-bound subagents * Plugins: add subagent lifecycle hook events * Core: emit subagent lifecycle hooks and decouple Discord bindings * Discord: handle subagent bind lifecycle via plugin hooks * Subagents: unify completion finalizer and split registry modules * Add subagent lifecycle events module * Hooks: fix subagent ended context key * Discord: share thread bindings across ESM and Jiti * Subagents: add persistent sessions_spawn mode for thread-bound sessions * Subagents: clarify thread intro and persistent completion copy * test(subagents): stabilize sessions_spawn lifecycle cleanup assertions * Discord: add thread-bound session TTL with auto-unfocus * Subagents: fail session spawns when thread bind fails * Subagents: cover thread session failure cleanup paths * Session: add thread binding TTL config and /session ttl controls * Tests: align discord reaction expectations * Agent: persist sessionFile for keyed subagent sessions * Discord: normalize imports after conflict resolution * Sessions: centralize sessionFile resolve/persist helper * Discord: harden thread-bound subagent session routing * Rebase: resolve upstream/main conflicts * Subagents: move thread binding into hooks and split bindings modules * Docs: add channel-agnostic subagent routing hook plan * Agents: decouple subagent routing from Discord * Discord: refactor thread-bound subagent flows * Subagents: prevent duplicate end hooks and orphaned failed sessions * Refactor: split subagent command and provider phases * Subagents: honor hook delivery target overrides * Discord: add thread binding kill switches and refresh plan doc * Discord: fix thread bind channel resolution * Routing: centralize account id normalization * Discord: clean up thread bindings on startup failures * Discord: add startup cleanup regression tests * Docs: add long-term thread-bound subagent architecture * Docs: split session binding plan and dedupe thread-bound doc * Subagents: add channel-agnostic session binding routing * Subagents: stabilize announce completion routing tests * Subagents: cover multi-bound completion routing * Subagents: suppress lifecycle hooks on failed thread bind * tests: fix discord provider mock typing regressions * docs/protocol: sync slash command aliases and delete param models * fix: add changelog entry for Discord thread-bound subagents (openclaw#21805) (thanks @onutc) --------- Co-authored-by: Shadow <[email protected]>

openclaw-barnacle Bot added docs Improvements or additions to documentation size: XS maintainer Maintainer-authored PR channel: discord Channel integration: discord gateway Gateway runtime agents Agent runtime and tooling size: XL and removed size: XS labels Feb 20, 2026

bobonutc Bot force-pushed the feat/thread-bound-subagents branch from cef0ba6 to 91e7da1 Compare February 20, 2026 16:05

osolmaz requested a review from thewilloftheshadow February 20, 2026 23:12

bobonutc Bot force-pushed the feat/thread-bound-subagents branch from 1cd2a69 to 7992111 Compare February 20, 2026 23:30

openclaw-barnacle Bot added the commands Command implementations label Feb 20, 2026

bobonutc Bot force-pushed the feat/thread-bound-subagents branch from 3e4557f to 6985179 Compare February 20, 2026 23:55

osolmaz marked this pull request as ready for review February 20, 2026 23:59

osolmaz changed the title ~~feat: thread-bound subagents plan (draft)~~ feat: thread-bound subagents on Discord Feb 21, 2026

chatgpt-codex-connector Bot reviewed Feb 21, 2026

View reviewed changes

Comment thread src/discord/monitor/message-handler.preflight.ts

Comment thread src/discord/monitor/thread-bindings.ts Outdated

greptile-apps Bot reviewed Feb 21, 2026

View reviewed changes

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

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

Comment thread src/discord/monitor/thread-bindings.ts Outdated

bobonutc Bot force-pushed the feat/thread-bound-subagents branch from 3bf7702 to d928dcf Compare February 21, 2026 09:40

openclaw deleted a comment from dutifulbob Feb 21, 2026

bobonutc Bot force-pushed the feat/thread-bound-subagents branch from d99fd4e to 582fdef Compare February 21, 2026 10:02

openclaw-barnacle Bot added app: web-ui App: web-ui app: macos App: macos labels Feb 21, 2026

onutc self-assigned this Feb 21, 2026

Onur added 6 commits February 21, 2026 16:09

docs: thread-bound subagents plan

74dcd75

docs: add exact thread-bound subagent implementation touchpoints

100f916

Docs: prioritize auto thread-bound subagent flow

eb52d8e

Docs: add ACP harness thread-binding extensions

b4b2677

Discord: add thread-bound session routing and auto-bind spawn flow

bf2f826

Subagents: add focus commands and ACP/session binding lifecycle hooks

edc993d

gwthm-in mentioned this pull request Mar 20, 2026

feat(telegram): Support thread=true for subagent spawning in Telegram groups #50709

Closed

clawsweeper Bot mentioned this pull request Apr 29, 2026

[Feature]: Session key override on bindings (cross-channel session unification) #14850

Closed

clawsweeper Bot mentioned this pull request May 3, 2026

fix(discord): preserve bound thread isolation across bot accounts #49434

Closed

20 tasks

clawsweeper Bot mentioned this pull request May 17, 2026

fix(discord): remove invalid message_reference from webhook payloads #39975

Closed

2 tasks

SebTardif mentioned this pull request May 20, 2026

fix(agents): add .catch() to fire-and-forget subagent lifecycle promises #84616

Merged

clawsweeper Bot mentioned this pull request May 31, 2026

fix(gateway): emit subagent_ended hook for api.runtime.subagent.run() (#59164) #87698

Merged

clawsweeper Bot mentioned this pull request Jun 21, 2026

feat(discord): show subagent progress #95604

Merged

This was referenced Jul 5, 2026

Plugin Hooks: Missing trace context for observability (messageId, runId in all hooks, parentSpanId) #50291

Open

[Bug]: Subagents can appear completed before the underlying delegated work is actually finished #50165

Open

clawsweeper Bot mentioned this pull request Jul 14, 2026

fix(discord): bound thread-binding sweep overlap #106599

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat: thread-bound subagents on Discord#21805

feat: thread-bound subagents on Discord#21805
onutc merged 49 commits into
openclaw:mainfrom
onutc:feat/thread-bound-subagents

onutc commented Feb 20, 2026 •

edited by osolmaz

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

Uh oh!

greptile-apps Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot commented Feb 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Uh oh!

Conversation

onutc commented Feb 20, 2026 • edited by osolmaz Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

config toggles

Routing and lifecycle fixes

Additional improvements

Testing

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

greptile-apps Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot commented Feb 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

onutc commented Feb 20, 2026 •

edited by osolmaz

Loading