feat: thread-bound subagents on Discord (#21805)

* 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 (#21805) (thanks @onutc)

---------

Co-authored-by: Shadow <hi@shadowing.dev>

src/discord/monitor/provider.lifecycle.test.ts

@@ -0,0 +1,106 @@
+import type { Client } from "@buape/carbon";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { RuntimeEnv } from "../../runtime.js";
+
+const {
+  attachDiscordGatewayLoggingMock,
+  getDiscordGatewayEmitterMock,
+  registerGatewayMock,
+  stopGatewayLoggingMock,
+  unregisterGatewayMock,
+  waitForDiscordGatewayStopMock,
+} = vi.hoisted(() => {
+  const stopGatewayLoggingMock = vi.fn();
+  return {
+    attachDiscordGatewayLoggingMock: vi.fn(() => stopGatewayLoggingMock),
+    getDiscordGatewayEmitterMock: vi.fn(() => undefined),
+    waitForDiscordGatewayStopMock: vi.fn(() => Promise.resolve()),
+    registerGatewayMock: vi.fn(),
+    unregisterGatewayMock: vi.fn(),
+    stopGatewayLoggingMock,
+  };
+});
+
+vi.mock("../gateway-logging.js", () => ({
+  attachDiscordGatewayLogging: attachDiscordGatewayLoggingMock,
+}));
+
+vi.mock("../monitor.gateway.js", () => ({
+  getDiscordGatewayEmitter: getDiscordGatewayEmitterMock,
+  waitForDiscordGatewayStop: waitForDiscordGatewayStopMock,
+}));
+
+vi.mock("./gateway-registry.js", () => ({
+  registerGateway: registerGatewayMock,
+  unregisterGateway: unregisterGatewayMock,
+}));
+
+describe("runDiscordGatewayLifecycle", () => {
+  beforeEach(() => {
+    attachDiscordGatewayLoggingMock.mockClear();
+    getDiscordGatewayEmitterMock.mockClear();
+    waitForDiscordGatewayStopMock.mockClear();
+    registerGatewayMock.mockClear();
+    unregisterGatewayMock.mockClear();
+    stopGatewayLoggingMock.mockClear();
+  });
+
+  it("cleans up thread bindings when exec approvals startup fails", async () => {
+    const { runDiscordGatewayLifecycle } = await import("./provider.lifecycle.js");
+
+    const start = vi.fn(async () => {
+      throw new Error("startup failed");
+    });
+    const stop = vi.fn(async () => undefined);
+    const threadStop = vi.fn();
+
+    await expect(
+      runDiscordGatewayLifecycle({
+        accountId: "default",
+        client: { getPlugin: vi.fn(() => undefined) } as unknown as Client,
+        runtime: {} as RuntimeEnv,
+        isDisallowedIntentsError: () => false,
+        voiceManager: null,
+        voiceManagerRef: { current: null },
+        execApprovalsHandler: { start, stop },
+        threadBindings: { stop: threadStop },
+      }),
+    ).rejects.toThrow("startup failed");
+
+    expect(start).toHaveBeenCalledTimes(1);
+    expect(stop).toHaveBeenCalledTimes(1);
+    expect(waitForDiscordGatewayStopMock).not.toHaveBeenCalled();
+    expect(unregisterGatewayMock).toHaveBeenCalledWith("default");
+    expect(stopGatewayLoggingMock).toHaveBeenCalledTimes(1);
+    expect(threadStop).toHaveBeenCalledTimes(1);
+  });
+
+  it("cleans up when gateway wait fails after startup", async () => {
+    const { runDiscordGatewayLifecycle } = await import("./provider.lifecycle.js");
+    waitForDiscordGatewayStopMock.mockRejectedValueOnce(new Error("gateway wait failed"));
+
+    const start = vi.fn(async () => undefined);
+    const stop = vi.fn(async () => undefined);
+    const threadStop = vi.fn();
+
+    await expect(
+      runDiscordGatewayLifecycle({
+        accountId: "default",
+        client: { getPlugin: vi.fn(() => undefined) } as unknown as Client,
+        runtime: {} as RuntimeEnv,
+        isDisallowedIntentsError: () => false,
+        voiceManager: null,
+        voiceManagerRef: { current: null },
+        execApprovalsHandler: { start, stop },
+        threadBindings: { stop: threadStop },
+      }),
+    ).rejects.toThrow("gateway wait failed");
+
+    expect(start).toHaveBeenCalledTimes(1);
+    expect(stop).toHaveBeenCalledTimes(1);
+    expect(waitForDiscordGatewayStopMock).toHaveBeenCalledTimes(1);
+    expect(unregisterGatewayMock).toHaveBeenCalledWith("default");
+    expect(stopGatewayLoggingMock).toHaveBeenCalledTimes(1);
+    expect(threadStop).toHaveBeenCalledTimes(1);
+  });
+});