Skip to content

Decouple mode="session" from thread binding requirement #53548

@yilong016

Description

@yilong016

Problem

sessions_spawn with mode="session" unconditionally requires thread: true:

if (spawnMode === "session" && !requestThreadBinding) return {
    status: "error",
    error: "mode=\"session\" requires thread=true so the ACP session can stay bound to a thread."
};

If the channel does not support thread bindings (e.g. Feishu, Signal, WhatsApp), the request fails with:

Thread bindings are unavailable for <channel>.

This makes persistent ACP sessions (and persistent subagent sessions) unusable on any channel without native thread support.

Why this coupling is unnecessary

Thread binding and persistent sessions serve two independent purposes:

Concern What it does Where it lives
Persistent session (mode="session") Keeps the ACP/subagent session alive for multi-turn interaction via sessions_send Backend (session lifecycle)
Thread binding (thread: true) Routes user messages in a thread directly to the bound session, bypassing the parent agent Frontend (message routing)

Thread binding is a delivery optimization — it lets users talk directly to a sub-session in a thread. But the session itself does not need a thread to exist. The parent agent can perfectly well relay messages to the session using sessions_send(label=...) or sessions_send(sessionKey=...).

Current user experience

On channels without thread support:

  • mode="session" → error → only mode="run" available → no multi-turn sessions
  • Workaround: use mode="run" with file-based state passing between invocations, which loses all session context

On channels with thread support (Discord):

  • Works as expected

Proposed behavior

Allow mode="session" without thread: true:

mode thread Behavior
"session" true Current behavior — session bound to thread, user messages route directly (unchanged)
"session" false or omitted Session persists, parent agent relays via sessions_send, output delivered to current conversation
"run" any One-shot execution (unchanged)

When mode="session" and thread is not set:

  • Create the persistent session normally
  • Return the childSessionKey / label so the caller can use sessions_send to continue the conversation
  • Deliver output back to the parent session (or the originating chat, same as mode="run")

Use cases unlocked

  1. Agent-as-orchestrator: Parent agent manages multi-turn sub-sessions programmatically (Feishu, WhatsApp, Signal, etc.)
  2. Multi-persona routing: Parent agent routes to different persistent sub-sessions based on context — this is a routing decision, not a thread decision
  3. Iterative coding workflows: Spawn a persistent Kiro/Claude/Codex session, send incremental instructions, accumulate context — on any channel

Environment

  • OpenClaw version: latest (checked source in dist/plugin-sdk/thread-bindings-SYAnWHuW.js)
  • Affected channels: all channels without native thread support (Feishu, Signal, WhatsApp, Google Chat, Line, etc.)
  • Works on: Discord (has native threads)

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Normal backlog priority with limited blast radius.clawsweeper:fix-shape-clearClawSweeper found a clear likely implementation shape for this issue.clawsweeper:needs-maintainer-reviewClawSweeper marked this issue as needing maintainer review before automation.clawsweeper:needs-product-decisionClawSweeper marked this issue as needing a product or behavior decision.clawsweeper:no-new-fix-prClawSweeper does not recommend queueing a new automated fix PR for this issue.clawsweeper:source-reproClawSweeper found a high-confidence source-level issue reproduction.impact:message-lossChannel message delivery can be lost, duplicated, or misrouted.impact:session-stateSession, memory, transcript, context, or agent state can drift or corrupt.issue-rating: 🦞 diamond lobsterVery strong issue quality with high-confidence source-level or clear reproduction.staleMarked as stale due to inactivity

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions