@sjawhar/opencode-legion-envoy 0.8.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "type": "module",
   "main": "dist/src/server.js",
   "exports": {
@@ -25,7 +25,7 @@
     "skills"
   ],
   "scripts": {
-    "build": "bun build src/server.ts bin/dispatch-mcp-shim.ts --outdir dist --target bun --format esm --external '@opencode-ai/*'",
+    "build": "bun build src/server.ts --root . --outdir dist --target bun --format esm --external '@opencode-ai/*'",
     "prepack": "bun run build && rm -rf skills && cp -r ../../skills skills",
     "typecheck": "bunx tsc --noEmit",
     "test": "bun test",
@@ -45,6 +45,7 @@
     "@legion/envoy-client": "0.1.0",
     "@types/bun": "latest",
     "solid-js": "^1.9.0",
-    "typescript": "^5.3.0"
+    "typescript": "^5.3.0",
+    "zod": "^4.1.8"
   }
 }

package/skills/AGENTS.md

@@ -8,6 +8,7 @@ event intake, process lifecycle, credentials, and role delivery.
 
 ```
 skills/
+├── dispatch/            # Raising a durable human question as a GitHub-issue thread
 ├── github/              # GitHub issue and pull-request operations
 ├── linear/              # Linear adapter instructions
 ├── legion-architect/    # Tree ownership, decomposition, gates, and scheduling

package/skills/dispatch/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: dispatch
+description: Use when you need a human decision from Sami or the user — asking a question, waiting on approval, saying "let me know", writing an end-of-message question block, picking between options with tradeoffs, or starting unattended/long-running work that will need input later. Raises the question as a durable GitHub-issue thread instead of a transcript question nobody will see.
+---
+
+# Dispatch
+
+`dispatch` turns a question into a durable, dashboard-visible GitHub-issue thread instead
+of a line buried in a transcript. A thread is **one decision, held as a conversation**: it
+opens with your question, the human replies, and if the reply changes the question you ask
+again on the same thread. It closes when the decision is settled, not when the first reply
+lands. Use it any time you would otherwise leave a question for a human to notice on their
+own.
+
+## When to dispatch
+
+- Any question not answerable at the keyboard in seconds.
+- Anything decision-shaped: a fork in approach, a tradeoff only the human can weigh, an
+  approval gate.
+- Anything you would otherwise write as an end-of-message question block and hope someone
+  reads.
+- Before you park on a blocker. Never leave a session idle on an unasked question.
+- Unattended or long-running work (Legion roles, background agents) that will need input
+  later — dispatch the question as soon as you know you'll need it, don't wait to be asked.
+
+## When NOT to dispatch
+
+- A one-word clarification the human is actively typing with you right now, in the same
+  turn — use the built-in `ask` tool instead. `dispatch` is for questions the reader has
+  not seen your transcript for; `ask` is for questions inside a live conversation.
+- Anything you can resolve yourself from tools or repo context. Dispatch is for genuine
+  human decisions, not a substitute for research.
+
+## Writing for the reader
+
+The reader has not seen your transcript. They are looking at a card on a dashboard between
+other things, and they will answer the question you wrote, not the one you meant.
+
+- **No nouns you coined this session.** No "the list above", "those items", "lane B",
+  "the eval-set thing". No internal identifiers — eval-set ids, lane names, hashes,
+  session ids — unless the question is about them. Expand every identifier on first use.
+  GitHub references may be bare: `#482`, `acme-org/example-repo#17`, or a URL — the
+  dashboard unfurls them into their titles.
+- **Structure over paragraphs.** `context` is at most three short paragraphs or a bullet
+  list, one idea each: what you are doing, what you found, why you are stuck. `question`
+  is a list: current state → desired state → your recommendation and why; the options
+  themselves go in `ask`, each tradeoff as its `description`. Don't just describe the
+  fork — say which branch you'd take and why.
+- **Options are buttons.** If you are offering choices, put them in `ask`; never enumerate
+  them in prose. A human answers a button in one click and the answer arrives structured;
+  a choice buried in a paragraph arrives as a sentence you have to interpret.
+- **Length caps.** `context` is at most 1200 characters, `question` at most 800. The
+  service refuses a longer call before anything reaches GitHub, naming the field and the
+  limit (`context is 1450 characters; the limit is 1200`); nothing is truncated. When you
+  hit a cap: move the choices into `ask`, cut background the reader does not need to
+  decide, and if there really are two decisions, open two threads.
+
+### Before / after
+
+A real thread, as first written — one block, coined nouns, options in prose:
+
+```
+subject:  "e2e submitter"
+context:  "So I've been going through the e2e harness like we discussed and the submitter
+           identity thing from earlier is still broken because the fixture in lane B uses
+           the shared bot account which means the assertions in eval-set 7f3a can't tell
+           who submitted, and the thing I mentioned about the env var not being set in CI
+           is also true so basically the list above doesn't apply until we pick one, and I
+           looked at how the other repo does it and they hardcode it which is fine for them
+           but not us, also the token minting issue is related but separate."
+question: "should I add E2E_SUBMITTER_EMAIL or use the bot or something else? I think
+           probably the env var but not sure, or maybe the hardcode thing, or the third
+           option where the harness reads it from git config. Let me know."
+```
+
+The same decision, written for the reader:
+
+```
+subject:  "E2E harness: which identity submits test PRs?"
+context:  "- The end-to-end test harness (acme-org/example-repo#17158) submits PRs as the
+             shared bot account, so a run cannot tell test submissions apart from real ones.
+           - CI sets no submitter identity today; the harness has no setting for one."
+question: "- Current: every test PR is authored by the shared bot.
+           - Desired: each run's PRs carry an identity that marks them as test submissions.
+           - Recommendation: a dedicated identity from one CI environment variable —
+             smallest change, no per-machine setup."
+ask:      [{ header: "Test submitter identity",
+             question: "Which identity should the harness use?",
+             options: [
+               { label: "Env var E2E_SUBMITTER_EMAIL", description: "one CI variable; the harness reads it" },
+               { label: "Shared bot (status quo)",      description: "no change; runs stay indistinguishable" },
+               { label: "Read from git config",         description: "per-machine setup; drifts" } ] }]
+```
+
+## How
+
+### Opening a thread
+
+```
+dispatch({
+  subject:  "Postgres migration: run online or take a maintenance window?",
+  context:  "- Implementing the users-table index migration for #482.
+             - The table has 40M rows; a plain CREATE INDEX locks writes for ~6 minutes
+               in the staging timing test I just ran.",
+  question: "- Current: no online-migration tooling in this repo's deploy pipeline.
+             - Desired: index added without a customer-visible write outage.
+             - Recommendation: the maintenance window — smaller blast radius, no
+               migration-runner change, inside the existing SLA.",
+  ask:      [{ header: "Approach", question: "Which way?",
+               options: [
+                 { label: "CREATE INDEX CONCURRENTLY", description: "no lock, ~25 min, needs a migration-runner change" },
+                 { label: "6-minute window at 03:00 UTC", description: "runner unchanged, brief write outage" } ] }],
+  urgency:  "med"
+})
+```
+
+- `subject`: one line, the decision — this is the issue title and the dashboard row.
+- `context` (required, ≤ 1200 chars): what you are doing, what you found, why you are stuck.
+- `question` (required, ≤ 800 chars): current → desired → recommendation (options live in
+  `ask`).
+- `ask` (optional): a list of `{ question, header?, options: [{ label, description? }],
+  multiple?, custom? }`. These render as buttons, always with an "Other (specify)"
+  free-text field beside them (`custom` does not change this); a plain reply on the thread
+  is also possible but arrives unstructured.
+- `urgency` (optional, default `med`): `low` — whenever convenient; `med` — needed today;
+  `high` — something will stall soon; `blocking` — you cannot proceed at all right now.
+- `repo` (optional): only to target a **different** repo than your working directory's
+  GitHub remote; the tool fills it from the cwd otherwise.
+- `parent` (optional): only when a real issue exists to attach to — `<n>` in the resolved
+  repo or `owner/name#<n>` elsewhere; `owner/name#<n>#<commentId>` also appends a
+  breadcrumb to that comment. For Legion roles, `parent` is the root issue you're working
+  under. Omitting it creates a standalone thread; don't invent a parent.
+
+The tool returns `{"thread": N, "url": "..."}`; that URL is the durable record.
+
+### Continuing a thread
+
+When the reply changes the question — the human challenged the premise, ruled out your
+recommendation, or asked for a variant you had not offered — re-ask **on the same thread**:
+
+```
+dispatch({
+  thread:   "482",                      // or "owner/name#482"
+  context:  "- You ruled out the maintenance window: the 03:00 UTC slot is now used by
+               the nightly export.
+             - CONCURRENTLY needs the migration runner to run outside a transaction.",
+  question: "- Current: the runner wraps every migration in a transaction.
+             - Desired: this one index built online.
+             - Recommendation: a one-off flag on the runner for non-transactional
+               migrations, used only by this migration.",
+  ask:      [{ header: "Runner change", question: "Add the non-transactional flag?",
+               options: [{ label: "Yes, one-off flag" }, { label: "No, hand-run the index" }] }]
+})
+```
+
+- `thread` replaces `subject`; `urgency`, `repo`, and `parent` are not accepted with it.
+  The thread must be open and be a dispatch thread; otherwise the tool says so
+  (`#N is not a dispatch thread`, `#N is closed; open a new thread`).
+- Same decision → same thread. A genuinely new decision → a new thread, even if it came
+  up in the reply.
+- **Read a challenge as an answer.** "Why not the bot?" is not a request for more prose;
+  it is the human declining your framing. Say what you now know, then ask the narrowed
+  question with new options — unless the challenge itself decides ("Why not the bot? Just
+  use the bot."), in which case act on it and re-ask nothing. A follow-up carries your
+  session's identity, so the human sees which conversation is asking even after a handoff.
+- The tool returns `{"thread": N, "url": "...", "comment": "..."}`.
+
+## After dispatching
+
+The reply arrives back in your own session as a steer — you do not fetch it. Keep every
+other non-blocked lane of work moving while you wait; a dispatch is not a reason to go
+idle. Never poll GitHub for the reply and never set up a watcher, cron, or retry loop to
+check on it — the delivery mechanism is already push-based. Each answer names the question
+it answers, so a thread with two open questions delivers two steers.
+
+If the tool errors because it can't resolve a repo (cwd has no GitHub remote and no
+qualified `parent` or `thread`), pass `repo=owner/name` (opening) or
+`thread=owner/name#<n>` (continuing) and retry.
+
+**Named risk:** a thread created in a repo where the Envoy GitHub App is not installed
+gets created successfully, but replies to it never route back to your session — you'll
+wait forever for a steer that can't arrive. The App is installed per account and per repo,
+not org-wide, and coverage changes; before relying on a reply from a repo you have not
+dispatched to before, check it: `gh api /repos/<owner>/<name>/installation` returns 200 when
+the App is installed there and 404 when it is not.
+
+## Manual fallback: the marker format
+
+If the tool itself is unavailable, the dashboard still understands a hand-written turn.
+Every dispatch marker is an HTML comment at the very start of the body — invisible on
+GitHub — followed by a blank line and the readable text.
+
+A follow-up question, posted with `gh issue comment <n> --body-file <file>`:
+
+```
+<!-- dispatch:ask
+requestId: <16 lowercase hex chars, unique to this follow-up>
+ask:
+    - askId: <the same 16 chars>
+      question: <the question>
+      header: <short header>
+      options:
+        - label: <label>
+          description: <one line>
+-->
+
+## Context
+
+<context>
+
+## Question
+
+<question>
+```
+
+A new thread, posted with `gh issue create --label dispatch-thread --title "<subject>" --body-file <file>`:
+
+```
+<!-- dispatch:thread
+requestId: <16 lowercase hex chars>
+urgency: med
+ask:
+    - askId: <the same 16 chars>
+      question: <the question>
+      options:
+        - label: <label>
+-->
+
+**<subject>**
+
+## Context
+
+<context>
+
+## Question
+
+<question>
+```
+
+`ask` may be omitted when there are no buttons to offer. A second ask on the same turn has
+`askId: <requestId>.1`, a third `.2`. A hand-posted turn carries no `origin`, so the
+dashboard cannot say which session asked, and nothing subscribes your session to a
+hand-created thread — subscribe it yourself with `envoy_subscribe` to
+`notifications.github.<owner>.<name>.issue.<n>.>` or the reply never arrives. Prefer the
+tool.

package/skills/envoy/SKILL.md

@@ -119,9 +119,9 @@ GitHub topics are **resource-scoped** — every event includes the resource type
 
 Examples:
 
-- `notifications.github.trajectory-labs-pbc.agent-c.pr.9880` (PR #9880 state changes)
-- `notifications.github.trajectory-labs-pbc.agent-c.pr.9880.comment` (comments on PR #9880)
-- `notifications.github.trajectory-labs-pbc.agent-c.issue.9909.>` (all events on issue #9909)
+- `notifications.github.example-org.example-repo.pr.9880` (PR #9880 state changes)
+- `notifications.github.example-org.example-repo.pr.9880.comment` (comments on PR #9880)
+- `notifications.github.example-org.example-repo.issue.9909.>` (all events on issue #9909)
 - `notifications.github.sjawhar.legion.pr.>` (all PR events across all PRs)
 - `notifications.github.sjawhar.legion.mention` (all @mentions repo-wide)
 - `notifications.github.sjawhar.legion.push.branch.main` (pushes to main)
@@ -143,10 +143,10 @@ Thread timestamps are normalized: `1234567890.123456` → `1234567890_123456`
 
 Examples:
 
-- `notifications.slack.T09FRELLTS8.C0A0DHVU8HE.message`
-- `notifications.slack.T09FRELLTS8.C0A0DHVU8HE.mention`
-- `notifications.slack.T09FRELLTS8.C0A0DHVU8HE.thread.1234567890_123456.message`
-- `notifications.slack.T09FRELLTS8.C0A0DHVU8HE.thread.1234567890_123456.mention`
+- `notifications.slack.T01234567.C0A0DHVU8HE.message`
+- `notifications.slack.T01234567.C0A0DHVU8HE.mention`
+- `notifications.slack.T01234567.C0A0DHVU8HE.thread.1234567890_123456.message`
+- `notifications.slack.T01234567.C0A0DHVU8HE.thread.1234567890_123456.mention`
 
 ### Ghost Wispr
 
@@ -200,6 +200,14 @@ Examples:
 
 You do NOT need to subscribe in order to send or publish.
 
+**Session ids are not stable for the life of a conversation.** On OMP, `/fork` and `/handoff`
+re-mint the session id while the conversation continues (esc-esc rewinds also did, on omp
+18.1.0–18.1.2 only); the extension rebinds automatically and injects an `envoy` notice naming
+the previous and new ids. When that notice arrives, any id you shared earlier (an
+`envoy_whoami` result quoted in a message, an id a peer saved) is stale — re-run
+`envoy_whoami` and re-announce yourself. Never treat a whoami result from earlier in the
+transcript as current when identifying yourself to peers.
+
 ### To wait for CI, PR checks, or other async work
 
 **Don't `sleep`-poll. Don't "check back in N minutes."** Subscribe to the event and continue with productive work — the system will wake the session when the event arrives.
@@ -226,7 +234,7 @@ If you have nothing else to do, end the response. The user is not your alarm clo
 
 ```text
 envoy_subscribe([
-  "notifications.slack.T09FRELLTS8.C0A0DHVU8HE.mention"
+  "notifications.slack.T01234567.C0A0DHVU8HE.mention"
 ])
 ```
 
@@ -234,7 +242,7 @@ envoy_subscribe([
 
 ```text
 envoy_subscribe([
-  "notifications.slack.T09FRELLTS8.C0A0DHVU8HE.thread.1234567890_123456.>"
+  "notifications.slack.T01234567.C0A0DHVU8HE.thread.1234567890_123456.>"
 ])
 ```
 
@@ -242,7 +250,7 @@ envoy_subscribe([
 
 ```text
 envoy_subscribe([
-  "notifications.slack.T09FRELLTS8.C0A0DHVU8HE.thread.1234567890_123456.message"
+  "notifications.slack.T01234567.C0A0DHVU8HE.thread.1234567890_123456.message"
 ])
 ```
 
@@ -250,23 +258,23 @@ envoy_subscribe([
 
 ```text
 envoy_subscribe([
-  "notifications.slack.T09FRELLTS8.C0A0DHVU8HE.thread.>"
+  "notifications.slack.T01234567.C0A0DHVU8HE.thread.>"
 ])
 ```
 
-### Subscribe to all PR events for agent-c
+### Subscribe to all PR events for example-repo
 
 ```text
 envoy_subscribe([
-  "notifications.github.trajectory-labs-pbc.agent-c.pr.>"
+  "notifications.github.example-org.example-repo.pr.>"
 ])
 ```
 
-### Subscribe controller to GitHub @mentions for agent-c
+### Subscribe controller to GitHub @mentions for example-repo
 
 ```text
 envoy_subscribe([
-  "notifications.github.trajectory-labs-pbc.agent-c.mention"
+  "notifications.github.example-org.example-repo.mention"
 ])
 ```
 
@@ -318,7 +326,7 @@ Catches all conversations and event kinds for the specified phone number.
 - Different sessions can subscribe to different channels/repos
 - Agent-to-agent delivery uses exact session IDs
 - `envoy_list()` distinguishes `live`, `registry`, and `both`; a `live` topic is receiving now even when the listener registry has not caught up.
-- For Slack, use the real `team_id` in topics (for example `T09FRELLTS8`), not a workspace slug like `trajectorylabs`
+- For Slack, use the real `team_id` in topics (for example `T01234567`), not a workspace slug like `acme`
 - GitHub mention routing is body-based because GitHub has no dedicated app mention webhook event
 
 ## Synthetic Smoke Test (WhatsApp — NATS Routing Only)

package/skills/legion-architect/SKILL.md

@@ -62,7 +62,8 @@ legion({ op: "label_add", issue: "<root issue>", label: "needs-approval" })
 dispatch({
   parent: "<root issue>",
   subject: "Legion design approval requested",
-  body: "<summary, specification, and requested decision>"
+  context: "<what the tree is, what triggered the gate>",
+  question: "<specification summary and the decision requested>"
 })
 ```
 

package/src/server.ts

@@ -3,13 +3,20 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { agentSubject } from "@legion/contracts";
 import { envoyDefaultsFromEnvironment } from "@legion/envoy-client/defaults";
+import { executeDispatch } from "@legion/envoy-client/dispatch-call";
+import { resolveDispatchConfig } from "@legion/envoy-client/dispatch-config";
+import {
+  DISPATCH_ARGUMENTS,
+  DISPATCH_TOOL_DESCRIPTION,
+  DISPATCH_TOOL_NAME,
+  DISPATCH_URGENCIES,
+  parseDispatchCall,
+} from "@legion/envoy-client/dispatch-contract";
 import { dispatchSubscriptionTopic } from "@legion/envoy-client/dispatch-subscribe";
 import { machineID } from "@legion/envoy-client/machine";
 import { envoyToolSpecs } from "@legion/envoy-client/tool-contract";
 import { createEnvoyClient } from "@legion/envoy-client/transport";
 import { tool } from "@opencode-ai/plugin/tool";
-import { loadEnvoyConfig } from "./config";
-import { buildDispatchMcpEntry, injectEnvoyMcp } from "./dispatch-mcp";
 import { logger } from "./log";
 import { resolvePort } from "./port";
 
@@ -36,9 +43,40 @@ const [
   sessionsSpec,
 ] = envoyToolSpecs;
 
+// The dispatch tool's LLM-facing schema, built with OpenCode's own zod
+// (`tool.schema`): OpenCode converts plugin schemas with that instance, and a
+// schema from another zod build loses its checks and descriptions on the way.
+// It mirrors `dispatchToolShape` from the contract field for field — the test
+// suite compares the two as JSON Schema so they cannot drift apart.
+const dispatchQuestionOption = tool.schema.strictObject({
+  label: tool.schema.string().min(1),
+  description: tool.schema.string().optional(),
+});
+const dispatchQuestion = tool.schema.strictObject({
+  question: tool.schema.string().min(1),
+  header: tool.schema.string().optional(),
+  options: tool.schema.array(dispatchQuestionOption).optional(),
+  multiple: tool.schema.boolean().optional(),
+  custom: tool.schema.boolean().optional(),
+});
+const dispatchArgs = {
+  subject: tool.schema.string().describe(DISPATCH_ARGUMENTS.subject).optional(),
+  thread: tool.schema.string().describe(DISPATCH_ARGUMENTS.thread).optional(),
+  context: tool.schema.string().describe(DISPATCH_ARGUMENTS.context),
+  question: tool.schema.string().describe(DISPATCH_ARGUMENTS.question),
+  ask: tool.schema.array(dispatchQuestion).describe(DISPATCH_ARGUMENTS.ask).optional(),
+  urgency: tool.schema.enum(DISPATCH_URGENCIES).describe(DISPATCH_ARGUMENTS.urgency).optional(),
+  repo: tool.schema.string().describe(DISPATCH_ARGUMENTS.repo).optional(),
+  parent: tool.schema.string().describe(DISPATCH_ARGUMENTS.parent).optional(),
+};
+
 export default async (input: { serverUrl: URL }) => {
   const cwd = process.cwd();
-  const config = await loadEnvoyConfig(cwd);
+  // One loader for the shared envoy.json contract. An invalid file refuses to
+  // load rather than run with dispatch silently off.
+  const dispatchConfig = resolveDispatchConfig(process.env, { cwd });
+  if (dispatchConfig.error !== null) throw new Error(`[envoy-plugin] ${dispatchConfig.error}`);
+  const dispatchServiceUrl = dispatchConfig.url;
   const envoyDefaults = envoyDefaultsFromEnvironment(process.env);
   const envoy = createEnvoyClient({ baseUrl: envoyDefaults.envoyUrl, fetch: globalThis.fetch });
   let activeSessionID: string | null = null;
@@ -153,13 +191,35 @@ export default async (input: { serverUrl: URL }) => {
     clearInterval(heartbeatInterval);
   });
 
+  // The dispatch tool is present iff envoy.json (or DISPATCH_MCP_URL) names a
+  // service. The plugin adds only what it alone knows — that this is OpenCode,
+  // and which session is asking.
+  const dispatchTool =
+    dispatchServiceUrl === null
+      ? {}
+      : {
+          [DISPATCH_TOOL_NAME]: tool({
+            description: DISPATCH_TOOL_DESCRIPTION,
+            args: dispatchArgs,
+            async execute(args, ctx) {
+              ctx.metadata({ title: "Dispatch" });
+              // Validate before the title lookup: an invalid call costs no request.
+              const call = parseDispatchCall(args);
+              const result = await executeDispatch({
+                call,
+                cwd: ctx.directory,
+                host: "opencode",
+                sessionId: ctx.sessionID,
+                sessionTitle: (await fetchTitle(ctx.sessionID)) ?? undefined,
+                serviceUrl: dispatchServiceUrl,
+              });
+              return JSON.stringify(result);
+            },
+          }),
+        };
+
   return {
-    config: (
-      cfg: { mcp?: Record<string, unknown>; skills?: { paths?: string[] } } & Record<
-        string,
-        unknown
-      >
-    ) => {
+    config: (cfg: { skills?: { paths?: string[] } } & Record<string, unknown>) => {
       // Serve the bundled legion skills to every session on this serve.
       if (skillsDirectory) {
         cfg.skills ??= {};
@@ -168,20 +228,6 @@ export default async (input: { serverUrl: URL }) => {
           cfg.skills.paths.push(skillsDirectory);
         }
       }
-      // Inject the envoy MCP entry into the OpenCode config when
-      // dispatch is enabled. Centralizing this in the plugin (instead of
-      // each user's opencode.json) means:
-      //   1. Registration is gated by `dispatch.enabled`
-      //   2. The bearer token is sourced per-CWD via the user's gh shim
-      //      (no env coordination needed)
-      //   3. Token rotation happens transparently inside the shim
-      //      subprocess — OpenCode never sees an expired token
-      const entry = buildDispatchMcpEntry({
-        dispatch: config.dispatch,
-      });
-      if (!entry) return;
-      const { warning } = injectEnvoyMcp(cfg, entry);
-      if (warning) logger.warn(warning);
     },
     event: async ({
       event,
@@ -250,9 +296,9 @@ export default async (input: { serverUrl: URL }) => {
       input: { tool: string; sessionID: string; callID: string; args: unknown },
       output: { title: string; output: string; metadata: unknown }
     ) => {
-      // When this session opens a Dispatch thread via the envoy_dispatch MCP
-      // tool, auto-subscribe it to the thread's GitHub topic so the human's
-      // reply is delivered back through Envoy. Best-effort — a subscribe
+      // When this session opens or continues a Dispatch thread via the native
+      // dispatch tool, auto-subscribe it to the thread's GitHub topic so the
+      // human's reply is delivered back through Envoy. Best-effort — a subscribe
       // failure must never surface to the model or fail the tool call.
       const topic = dispatchSubscriptionTopic(input.tool, output.output);
       if (!topic) return;
@@ -276,6 +322,7 @@ export default async (input: { serverUrl: URL }) => {
       clearInterval(heartbeatInterval);
     },
     tool: {
+      ...dispatchTool,
       envoy_subscribe: tool({
         description: subscribeSpec.description,
         args: { topics: tool.schema.array(tool.schema.string()) },