@sjawhar/opencode-legion-envoy 1.25.0 → 1.27.0

package/README.md

@@ -16,23 +16,28 @@ This package exposes:
 - `dispatch_ask`
 - `dispatch_edit_ask`
 - `dispatch_resolve_ask`
+- `dispatch_follow`
 - `dispatch_comment`
 - `dispatch_suggest`
 - `dispatch_message`
 - `dispatch_doc_edit`
 - `dispatch_doc_read`
+- `dispatch_request_approval`
 - `dispatch_artifact`
 - `dispatch_read`
 - `dispatch_search`
+- `dispatch_open_asks`
 
-The twelve native `dispatch_*` tools create and read Dispatch issues, asks, comments,
+The fifteen native `dispatch_*` tools create and read Dispatch issues, asks, comments,
 documents, and artifacts, or search all of them. They are present when `dispatch.enabled`
 resolves a server URL and bearer token from envoy.json (`~/.config/opencode/envoy.json`, merged
 with `<repo>/.opencode/envoy.json`) or the `DISPATCH_URL` and `DISPATCH_TOKEN` environment
 variables; `dispatch.enabled: true` without `dispatch.serverUrl` targets `http://localhost:8766`.
-Each issue-scoped call fills the target issue from the session working directory, stamps it with
-the OpenCode session id and title, and stores a successful mutation's `details.topic` as tool
-metadata so the host subscribes to that exact Dispatch topic.
+Each issue-scoped call fills the target issue from the session working directory and stamps it with
+the OpenCode session id and title. No write subscribes the session to an issue or document: a
+session follows the asks it opens or replies to (their answers and replies reach it directly),
+`dispatch_follow` leaves or rejoins one, and every write result names the `envoy_subscribe` line
+for the whole owner.
 
 `dispatch_artifact` accepts exactly one upload source: a local `path`, or inline `content`.
 An architect can post a specification directly with

package/dist/src/server.js

@@ -13682,6 +13682,11 @@ var SubscriptionRemovedEventPayloadSchema = object({
   pending: boolean2().optional(),
   request_event_id: number2().int().positive().optional()
 });
+var AskFollowerEventPayloadSchema = object({
+  ask_id: string2().optional(),
+  session_id: string2().optional(),
+  by: object({ kind: string2(), id: string2().optional() }).passthrough().optional()
+});
 // ../contracts/src/dispatch-snippet.ts
 var HTML_ENTITIES = [
   ["&lt;", "<"],
@@ -13806,7 +13811,7 @@ var dispatchToolSpecs = [
       options: z.array(z.object({
         label: z.string().describe("Selectable option label."),
         description: z.string().describe("Optional option context.").optional()
-      }), { max: 8 }).describe("Optional choices, at most 8.").optional(),
+      }), { max: 8 }).describe("Up to 8 choices, each an object { label, description? } (never a bare string).").optional(),
       multiple: z.boolean().describe("Whether multiple choices may be selected.").optional(),
       urgency: z.enum(ASK_URGENCIES).describe("Optional decision urgency.").optional(),
       anchor: z.object({
@@ -13847,6 +13852,15 @@ var dispatchToolSpecs = [
       reason: z.string({ min: 1 }).describe("Why the open ask no longer needs a human answer.")
     })
   },
+  {
+    name: "dispatch_follow",
+    description: "Follow or unfollow an ask. Every session that opens or replies to an ask follows it: its answer, " + "edits, resolution, and replies reach that session directly. Unfollow to stop; follow to rejoin or " + "to hear an ask you never wrote to. Whole-issue subscription is separate: envoy_subscribe " + "notifications.dispatch.issue.<KEY>.>",
+    arguments: (z) => ({
+      ask: z.string().describe("Full ask id (uuid)."),
+      action: z.enum(["follow", "unfollow"]).describe("follow | unfollow")
+    }),
+    strict: true
+  },
   {
     name: "dispatch_comment",
     description: "Add review feedback to an issue or project document quote, or reply to a question asked with dispatch_ask. " + "Do not use it for an exact replacement; use " + `dispatch_suggest instead. A quote anchor is pinned to its block. Body is at most 2,000 characters. ${OWNER_REFERENCE}`,
@@ -13858,7 +13872,7 @@ var dispatchToolSpecs = [
       quote: z.string().describe("Optional exact quoted document text.").optional(),
       occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based occurrence of quote.").optional(),
       body: z.string({ max: 2000 }).describe("Review comment, at most 2,000 characters."),
-      reply_to: z.string().describe("Full id of a comment to reply to; replying to any comment in a thread continues that " + "thread (an ask's clarification thread included).").optional(),
+      reply_to: z.string().describe("A comment id (uuid); replying to any comment in a thread continues that thread (an " + "ask's clarification thread included). To reply to an ask, use reply_to_ask with the " + "ask id instead.").optional(),
       reply_to_ask: z.string().describe("Optional ask id to reply to, threading this comment under that question. Mutually " + "exclusive with reply_to.").optional(),
       turn: z.enum(["agent", "human"]).describe("Only with reply_to_ask: who holds the turn after this reply. agent: a progress note - " + "you keep the turn and the ask stays 'Waiting on agents' for the human; human (default): " + "you need the human to act - the ask returns to 'Waiting on you'.").optional()
     }),
@@ -13890,7 +13904,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_doc_edit",
-    description: "Apply deterministic document edits, including retyping an identified paragraph into a schema-declared typed block. " + "Do not use it for review feedback or for reading; use dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. " + "For replace, delete, and quote insert anchors, find text exactly as rendered: omit Markdown markers such as backticks or asterisks. " + `The spec (or any document) holds requirements, design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
+    description: "Apply deterministic document edits, including retyping an identified paragraph into a schema-declared typed block. " + "Do not use it for review feedback or for reading; use dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. " + 'For replace, delete, and quote insert anchors, find text as rendered: inline Markdown (**bold**, `code`) is tolerated; a leading \'# \' matches a heading. Insert anchors also accept "start", "end", and "heading:<exact heading text>". ' + `The spec (or any document) holds requirements, design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
@@ -13898,12 +13912,12 @@ var dispatchToolSpecs = [
       ref: z.string().describe("Optional dispatch:// issue or document reference.").optional(),
       ops: z.array(z.object({
         op: z.enum(DOC_EDIT_OPS).describe("Edit operation."),
-        find: z.string().describe("Text to find for replace or delete.").optional(),
+        find: z.string().describe("Text of the target block as rendered, for replace or delete; inline markdown (**bold**, `code`) is tolerated; a leading '# ' matches a heading.").optional(),
         with: z.string().describe("Replacement text for replace.").optional(),
         occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based match occurrence.").optional(),
         markdown: z.string().describe("Markdown to insert.").optional(),
-        after: z.string().describe("Anchor after which to insert.").optional(),
-        before: z.string().describe("Anchor before which to insert.").optional(),
+        after: z.string().describe(`Insert after this anchor: a quote of the neighbouring block's text, or one of "start", "end", "heading:<exact heading text>".`).optional(),
+        before: z.string().describe(`Insert before this anchor: a quote of the neighbouring block's text, or one of "start", "end", "heading:<exact heading text>".`).optional(),
         block: z.string().describe("Block id to retype.").optional(),
         type: z.string().describe("Typed block name for retype.").optional(),
         attributes: z.unknown().describe("Typed block attributes for retype.").optional()
@@ -14390,6 +14404,9 @@ function canonicalRepo(owner, repo) {
   return `${owner.trim().toLowerCase()}/${repo.trim().toLowerCase().replace(/\.git$/, "")}`;
 }
 // ../contracts/src/tool-schema.ts
+function overCapMessage(length, max) {
+  return `is ${length - max} characters over the ${max}-character limit (${length}/${max})`;
+}
 function zodSchemaApi(zod) {
   const api = zod;
   return {
@@ -14397,8 +14414,12 @@ function zodSchemaApi(zod) {
       let schema = api.string();
       if (opts.min !== undefined)
         schema = schema.min(opts.min);
-      if (opts.max !== undefined)
-        schema = schema.max(opts.max);
+      if (opts.max !== undefined) {
+        const max = opts.max;
+        schema = schema.max(max, {
+          error: (issue) => overCapMessage(typeof issue.input === "string" ? issue.input.length : max + 1, max)
+        });
+      }
       return schema;
     },
     number: (opts = {}) => {
@@ -14597,6 +14618,24 @@ function resolveDispatchConfig(env, options = {}) {
 // ../envoy-client/src/dispatch-execute.ts
 import { resolve as resolvePath } from "path";
 
+// ../envoy-client/src/ask-answer.ts
+var HEAD_LENGTH = 120;
+function textHead(text, limit = HEAD_LENGTH) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > limit ? `${flat.slice(0, limit)}\u2026` : flat;
+}
+function askAnswerText(answer) {
+  if (answer === null || answer === undefined)
+    return "";
+  const selected = (answer.selected ?? []).join(", ");
+  const text = answer.text ?? "";
+  if (text === "")
+    return selected;
+  if (selected === "")
+    return text;
+  return `${selected} - ${text}`;
+}
+
 // ../envoy-client/src/dispatch-cwd.ts
 import { execFile } from "child_process";
 import { promisify } from "util";
@@ -14778,6 +14817,9 @@ class DispatchClient {
   async comment(issue, input) {
     return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue), "comments"], input);
   }
+  async listIssueAsks(issue, state) {
+    return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "asks"], undefined, state === undefined ? undefined : { state });
+  }
   async getArtifactAsks(id, state) {
     return this.#json("GET", ["api", "v1", "artifacts", id, "asks"], undefined, state === undefined ? undefined : { state });
   }
@@ -14854,6 +14896,12 @@ class DispatchClient {
   async getAsk(id) {
     return this.#json("GET", ["api", "v1", "asks", id]);
   }
+  async followAsk(id, sessionId, actor) {
+    await this.#json("PUT", ["api", "v1", "asks", id, "followers", sessionId], { actor });
+  }
+  async unfollowAsk(id, sessionId, actor) {
+    await this.#json("DELETE", ["api", "v1", "asks", id, "followers", sessionId], { actor });
+  }
   async getComment(id) {
     return this.#json("GET", ["api", "v1", "comments", id]);
   }
@@ -14976,13 +15024,144 @@ class DispatchClient {
   }
 }
 
+// ../envoy-client/src/tool-input-errors.ts
+class ToolInputError extends Error {
+  tool;
+  problems;
+  constructor(tool, problems) {
+    const count = problems.length;
+    super([
+      `${tool} was not called: ${count} problem${count === 1 ? "" : "s"}`,
+      ...problems.map((problem) => `- ${problem}`)
+    ].join(`
+`));
+    this.name = "ToolInputError";
+    this.tool = tool;
+    this.problems = problems;
+  }
+}
+function unwrap(schema) {
+  let current = schema;
+  while (current !== undefined) {
+    const def = current.def;
+    if (!("innerType" in def) || !(def.type === "optional" || def.type === "nullable" || def.type === "default"))
+      break;
+    current = def.innerType;
+  }
+  return current;
+}
+function shapeOf(schema) {
+  const unwrapped = unwrap(schema);
+  if (unwrapped === undefined)
+    return;
+  const def = unwrapped.def;
+  return def.type === "object" && "shape" in def ? def.shape : undefined;
+}
+function schemaAt(schema, path) {
+  let current = schema;
+  for (const key of path) {
+    const unwrapped = unwrap(current);
+    if (unwrapped === undefined)
+      return;
+    const def = unwrapped.def;
+    if (def.type === "object" && "shape" in def) {
+      current = shapeOf(unwrapped)?.[String(key)];
+    } else if (def.type === "array" && "element" in def) {
+      current = def.element;
+    } else {
+      return;
+    }
+  }
+  return unwrap(current);
+}
+function describeInput(value) {
+  if (value === null)
+    return "null";
+  if (Array.isArray(value))
+    return "an array";
+  switch (typeof value) {
+    case "number":
+    case "boolean":
+      return String(value);
+    case "string":
+      return "a string";
+    case "object":
+      return "an object";
+    default:
+      return typeof value;
+  }
+}
+function describeExpected(expected, schema) {
+  switch (expected) {
+    case "int":
+      return "an integer";
+    case "object": {
+      const shape = shapeOf(schema);
+      const keys = shape === undefined ? [] : Object.entries(shape).map(([key, field]) => `${key}${field.def.type === "optional" ? "?" : ""}`);
+      return keys.length === 0 ? "an object" : `an object {${keys.join(", ")}}`;
+    }
+    case "array":
+      return "an array";
+    default:
+      return `a ${expected}`;
+  }
+}
+function formatZodIssues(issues, schema) {
+  const allowed = Object.keys(shapeOf(schema) ?? {}).join(", ");
+  return issues.flatMap((issue) => {
+    const path = issue.path.map(String).join(".");
+    switch (issue.code) {
+      case "invalid_type":
+        return issue.input === undefined ? [`${path} is required (${issue.expected})`] : [
+          `${path} must be ${describeExpected(issue.expected, schemaAt(schema, issue.path))}, not ${describeInput(issue.input)}`
+        ];
+      case "unrecognized_keys":
+        return issue.keys.map((key) => `unknown field "${key}"; allowed: ${allowed}`);
+      case "invalid_value":
+        return [
+          `${path} must be one of ${issue.values.map(String).join("|")}; got ${JSON.stringify(issue.input)}`
+        ];
+      case "too_big":
+        if (issue.origin === "array" && Array.isArray(issue.input)) {
+          return [`${path} has ${issue.input.length} items; the limit is ${issue.maximum}`];
+        }
+        return [`${path} ${issue.message}`];
+      case "custom":
+        return [issue.message];
+      default:
+        return [path === "" ? issue.message : `${path}: ${issue.message}`];
+    }
+  });
+}
+
 // ../envoy-client/src/dispatch-execute.ts
+function issueTopic(key) {
+  return { label: key, topic: dispatchIssueSubject(key, ">") };
+}
+function documentTopic(artifact) {
+  return {
+    label: `${artifact.project}/${artifact.slug}`,
+    topic: dispatchDocumentSubject(artifact.project, artifact.slug, ">")
+  };
+}
+function resolvedTopic(resolved) {
+  if (resolved.owner.kind === "project")
+    return documentTopic(resolved.artifact);
+  if (resolved.issue === undefined)
+    throw new Error("issue document is missing its issue");
+  return issueTopic(resolved.issue.key);
+}
+function notSubscribed(owner) {
+  return `(not subscribed to ${owner.label}; envoy_subscribe ${owner.topic} for every event on it)`;
+}
+function followsAsk(owner) {
+  return `You follow this ask: its answer and replies reach you directly. For every event on ${owner.label}: envoy_subscribe ${owner.topic}`;
+}
 function documentResultDetails(artifact) {
   return {
     project: artifact.project,
     artifact: artifact.id,
-    document: `${artifact.project}/${artifact.slug}`,
-    topic: dispatchDocumentSubject(artifact.project, artifact.slug, ">")
+    document: `${artifact.project}/${artifact.slug}`
   };
 }
 function writeResultDetails(resolved, fields) {
@@ -14991,19 +15170,11 @@ function writeResultDetails(resolved, fields) {
   }
   if (resolved.issue === undefined)
     throw new Error("issue document is missing its issue");
-  return {
-    issue: resolved.issue.key,
-    topic: dispatchIssueSubject(resolved.issue.key, ">"),
-    ...fields
-  };
+  return { issue: resolved.issue.key, ...fields };
 }
-async function askResultDetails(client, ask, resolved) {
+async function askOwnerDetails(client, ask, resolved) {
   if (ask.issue_key !== null) {
-    return {
-      issue: ask.issue_key,
-      topic: dispatchIssueSubject(ask.issue_key, ">"),
-      ask: ask.id
-    };
+    return { issue: ask.issue_key, ask: ask.id };
   }
   if (ask.artifact_id === undefined || ask.artifact_id === null) {
     throw new Error("document ask is missing its artifact ID");
@@ -15011,6 +15182,9 @@ async function askResultDetails(client, ask, resolved) {
   const artifact = resolved?.artifact ?? await client.getArtifact(ask.artifact_id);
   return { ...documentResultDetails(artifact), ask: ask.id };
 }
+async function followedAskDetails(client, ask, resolved) {
+  return { ...await askOwnerDetails(client, ask, resolved), follows: { ask: ask.id } };
+}
 var nativeIssueKeyPattern = /^[A-Z][A-Z0-9]{1,9}-[0-9]+$/;
 var externalIssueRefPattern = /^([^/\s]+)\/([^/\s#]+)#([1-9][0-9]*)$/;
 var bareIssueNumberPattern = /^[1-9][0-9]*$/;
@@ -15018,6 +15192,7 @@ var issueFreeTools = {
   dispatch_issue: true,
   dispatch_edit_ask: true,
   dispatch_resolve_ask: true,
+  dispatch_follow: true,
   dispatch_search: true,
   dispatch_open_asks: true
 };
@@ -15070,23 +15245,19 @@ function askUrgency(args) {
   return ASK_URGENCIES.find((urgency) => urgency === value);
 }
 function askKind(args) {
-  const value = optionalString(args, "kind");
-  if (value === undefined || value === "action")
-    return value;
-  throw new Error("kind must be action");
+  return optionalString(args, "kind") === "action" ? "action" : undefined;
 }
-function askQuestionWithRef(args) {
-  const question = stringArg(args, "question");
-  const ref = optionalString(args, "ref");
-  if (ref === undefined || question.includes(ref))
-    return question;
-  const withRef = `${question}
+var maxAskQuestion16 = 800;
+function questionWithRef(question, ref) {
+  return ref === undefined || question.includes(ref) ? question : `${question}
 
 Ref: ${ref}`;
-  if (withRef.length > 800) {
-    throw new Error("question plus ref must be at most 800 characters");
-  }
-  return withRef;
+}
+function askQuestionWithRef(args) {
+  return questionWithRef(stringArg(args, "question"), optionalString(args, "ref"));
+}
+function askQuestionProblem(withRef) {
+  return withRef.length > maxAskQuestion16 ? `question plus ref ${overCapMessage(withRef.length, maxAskQuestion16)}; shorten the question or drop the ref` : undefined;
 }
 function parseDispatchRef(ref) {
   const projectDocument = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9})\/artifact\/([^/@]+)(?:@v(\d+))?(?:\/(ask|comment)\/([^/]+))?$/);
@@ -15108,7 +15279,8 @@ function parseDispatchRef(ref) {
     return {
       owner: { kind: "project", project },
       kind: targetKind,
-      id: targetID
+      id: targetID,
+      artifact
     };
   }
   const issueReference = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9}-[1-9][0-9]*)(?:\/(spec)|\/(log)|\/(children)|\/artifact\/([^/@]+)(?:@v(\d+))?|\/ask\/([^/]+)|\/comment\/([^/]+)|\/message\/([^/]+))?$/);
@@ -15140,60 +15312,171 @@ function parseDispatchRef(ref) {
     return { owner, kind: "message", id: message };
   return { owner, kind: "issue", id: issue };
 }
+var uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var askIdProblem = "ask must be a bare ask id or a dispatch://.../ask/<id> reference";
+var messageIdProblem = "in_reply_to must be a full message id (uuid) or a dispatch://KEY/message/<id> reference";
 function askId(args) {
   const ask = stringArg(args, "ask");
-  if (!ask.startsWith("dispatch://"))
-    return ask;
-  const reference = parseDispatchRef(ask);
-  if (reference?.kind !== "ask") {
-    throw new Error("ask must be a bare ask id or a dispatch://.../ask/<id> reference");
+  return ask.startsWith("dispatch://") ? parseDispatchRef(ask)?.id ?? ask : ask;
+}
+function messageIdOf(value) {
+  const id = value.startsWith("dispatch://") ? (() => {
+    const reference = parseDispatchRef(value);
+    return reference?.kind === "message" ? reference.id : undefined;
+  })() : value;
+  return id !== undefined && uuidPattern.test(id) ? id : undefined;
+}
+var idPrefixPattern = /^[0-9a-f][0-9a-f-]{7,}$/i;
+async function resolveIdPrefix(tool, kind, ref, list) {
+  if (uuidPattern.test(ref.id))
+    return ref.id;
+  const ownerName = ref.owner.kind === "issue" ? ref.owner.issue : `${ref.owner.project}/${ref.artifact}`;
+  if (!idPrefixPattern.test(ref.id)) {
+    throw new ToolInputError(tool, [
+      `${kind} id ${ref.id} must be a full uuid or a prefix of at least 8 hex characters`
+    ]);
   }
-  return reference.id;
+  const prefix = ref.id.toLowerCase();
+  const matches = (await list()).filter((item) => item.id.toLowerCase().startsWith(prefix));
+  if (matches.length === 1 && matches[0] !== undefined)
+    return matches[0].id;
+  throw new ToolInputError(tool, [
+    matches.length === 0 ? `${kind} id ${ref.id} matches none of the ${kind}s on ${ownerName}; use the full id` : `${kind} id ${ref.id} matches ${matches.length} ${kind}s on ${ownerName}; use the full id`
+  ]);
 }
 function messageInReplyTo(args) {
   const inReplyTo = optionalString(args, "in_reply_to");
-  if (inReplyTo === undefined || !inReplyTo.startsWith("dispatch://"))
-    return inReplyTo;
-  const reference = parseDispatchRef(inReplyTo);
-  if (reference?.kind !== "message") {
-    throw new Error("in_reply_to must be a bare message id or a dispatch://.../message/<id> reference");
+  return inReplyTo === undefined ? undefined : messageIdOf(inReplyTo);
+}
+function argumentProblems(tool, args) {
+  const problems = [];
+  switch (tool) {
+    case "dispatch_ask": {
+      const question = optionalString(args, "question");
+      const ref = optionalString(args, "ref");
+      if (question !== undefined && ref !== undefined && question.length <= maxAskQuestion16) {
+        const problem = askQuestionProblem(questionWithRef(question, ref));
+        if (problem !== undefined)
+          problems.push(problem);
+      }
+      break;
+    }
+    case "dispatch_edit_ask":
+    case "dispatch_resolve_ask": {
+      const ask = optionalString(args, "ask");
+      if (ask?.startsWith("dispatch://") && parseDispatchRef(ask)?.kind !== "ask") {
+        problems.push(askIdProblem);
+      }
+      break;
+    }
+    case "dispatch_comment": {
+      if (optionalString(args, "quote") !== undefined && optionalString(args, "artifact") === undefined) {
+        problems.push("artifact is required when quote is supplied");
+      }
+      if (optionalString(args, "reply_to") !== undefined && optionalString(args, "reply_to_ask") !== undefined) {
+        problems.push("reply_to and reply_to_ask cannot both be set");
+      }
+      break;
+    }
+    case "dispatch_message": {
+      const inReplyTo = optionalString(args, "in_reply_to");
+      if (inReplyTo !== undefined && messageIdOf(inReplyTo) === undefined) {
+        problems.push(messageIdProblem);
+      }
+      break;
+    }
   }
-  return reference.id;
+  return problems;
 }
+function dispatchRefFromUrl(value, serverUrl) {
+  let url;
+  let origin;
+  try {
+    url = new URL(value);
+    origin = new URL(serverUrl).origin;
+  } catch {
+    return;
+  }
+  if (url.origin !== origin)
+    return;
+  const versionOf = (name) => {
+    const value = url.searchParams.get(name);
+    return value !== null && /^[1-9][0-9]*$/.test(value) ? `@v${value}` : "";
+  };
+  const issuePage = url.pathname.match(/^\/issues\/([A-Z][A-Z0-9]{1,9}-[1-9][0-9]*)(?:\/(spec|log|conversation|children)|\/artifacts\/([^/]+)|\/asks\/([^/]+)|\/comments\/([^/]+)|\/messages\/([^/]+))?\/?$/);
+  if (issuePage) {
+    const [, key, page, artifact, ask, comment, message] = issuePage;
+    const version = versionOf("v");
+    if (page === "spec" && version !== "")
+      return `dispatch://${key}/artifact/spec${version}`;
+    if (page !== undefined)
+      return `dispatch://${key}/${page === "conversation" ? "log" : page}`;
+    if (artifact !== undefined) {
+      return `dispatch://${key}/artifact/${decodeURIComponent(artifact)}${version}`;
+    }
+    if (ask !== undefined)
+      return `dispatch://${key}/ask/${ask}`;
+    if (comment !== undefined)
+      return `dispatch://${key}/comment/${comment}`;
+    if (message !== undefined)
+      return `dispatch://${key}/message/${message}`;
+    return `dispatch://${key}`;
+  }
+  const documentPage = url.pathname.match(/^\/projects\/([A-Z][A-Z0-9]{1,9})\/documents\/([^/]+)\/?$/);
+  if (!documentPage)
+    return;
+  const [, project, slug] = documentPage;
+  const document = `dispatch://${project}/artifact/${decodeURIComponent(slug ?? "")}${versionOf("version")}`;
+  const ask = url.searchParams.get("ask");
+  if (ask !== null)
+    return `${document}/ask/${ask}`;
+  const comment = url.searchParams.get("comment");
+  if (comment !== null)
+    return `${document}/comment/${comment}`;
+  return document;
+}
+var refGrammarProblem = "ref must be a valid dispatch:// reference such as dispatch://KEY-1, " + "dispatch://KEY-1/ask/<uuid>, dispatch://KEY-1/comment/<uuid>, " + "dispatch://KEY-1/message/<uuid>, dispatch://KEY-1/artifact/<slug>, or " + "dispatch://PROJECT/artifact/<document-ref> (an artifact id, slug, or filename); " + "a dashboard URL on this Dispatch server is accepted too";
+var ownerRequiredProblem = "issue is required; supply issue or set LEGION_ISSUE";
 function toolSchema(tool) {
   const spec = dispatchToolSpecs.find((candidate) => candidate.name === tool);
   if (!spec)
     throw new Error(`Unknown Dispatch tool: ${tool}`);
   return dispatchToolSchema(spec, zodSchemaApi(exports_external), { strict: true });
 }
-async function resolveOwnerArguments(tool, args, cwd, env, exec) {
+async function resolveOwnerArguments(tool, input, cwd, env, exec, serverUrl, problems) {
   if (issueFreeTools[tool] === true)
-    return { args, ref: null, owner: null };
-  const refArgument = args.ref;
-  if (tool === "dispatch_ask" && typeof refArgument === "string" && !refArgument.startsWith("dispatch://")) {
-    throw new Error("ref must be a dispatch:// reference");
-  }
-  const ref = typeof refArgument === "string" ? parseDispatchRef(refArgument) ?? (() => {
-    throw new Error("ref must be a valid dispatch:// reference such as dispatch://KEY-1, " + "dispatch://KEY-1/ask/<uuid>, dispatch://KEY-1/comment/<uuid>, " + "dispatch://KEY-1/message/<uuid>, dispatch://KEY-1/artifact/<slug>, or " + "dispatch://PROJECT/artifact/<document-ref> (an artifact id, slug, or filename)");
-  })() : null;
+    return { args: input, ref: null, owner: null };
+  const refArgument = input.ref;
+  let ref = null;
+  let args = input;
+  if (typeof refArgument === "string") {
+    const refText = dispatchRefFromUrl(refArgument, serverUrl) ?? refArgument;
+    if (refText !== refArgument)
+      args = { ...input, ref: refText };
+    ref = parseDispatchRef(refText);
+    if (ref === null) {
+      problems.push(tool === "dispatch_ask" && !refText.startsWith("dispatch://") ? "ref must be a dispatch:// reference" : refGrammarProblem);
+    }
+  }
   const issueArgument = args.issue;
   const projectArgument = args.project;
   const artifactArgument = args.artifact;
   const versionArgument = args.version;
   if (issueArgument !== undefined && projectArgument !== undefined) {
-    throw new Error("exactly one of issue and project is required");
+    problems.push("exactly one of issue and project is required");
   }
   if (typeof projectArgument === "string") {
     if (!/^[A-Z][A-Z0-9]{1,9}$/.test(projectArgument)) {
-      throw new Error("project must be a project key such as CORE");
+      problems.push("project must be a project key such as CORE");
     }
-    if (ref?.owner.kind === "project" && (ref.owner.project !== projectArgument || artifactArgument !== undefined && artifactArgument !== ref.id)) {
-      throw new Error("project and ref must name the same document");
+    const refDocument = ref?.owner.kind === "project" ? ref.artifact ?? ref.id : undefined;
+    if (ref?.owner.kind === "project" && (ref.owner.project !== projectArgument || artifactArgument !== undefined && artifactArgument !== refDocument)) {
+      problems.push("project and ref must name the same document");
     }
     return {
       args: {
         ...args,
-        ...artifactArgument === undefined && ref?.owner.kind === "project" ? { artifact: ref.id } : {},
+        ...artifactArgument === undefined && refDocument !== undefined ? { artifact: refDocument } : {},
         ...versionArgument === undefined && ref?.version !== undefined ? { version: ref.version } : {}
       },
       ref,
@@ -15205,7 +15488,7 @@ async function resolveOwnerArguments(tool, args, cwd, env, exec) {
       args: {
         ...args,
         project: ref.owner.project,
-        ...artifactArgument === undefined ? { artifact: ref.id } : {},
+        ...artifactArgument === undefined ? { artifact: ref.artifact ?? ref.id } : {},
         ...versionArgument === undefined && ref.version !== undefined ? { version: ref.version } : {}
       },
       ref,
@@ -15226,20 +15509,25 @@ async function resolveOwnerArguments(tool, args, cwd, env, exec) {
     };
   }
   const legionIssue = env.LEGION_ISSUE;
-  if (!legionIssue)
-    throw new Error("issue is required; supply issue or set LEGION_ISSUE");
+  if (!legionIssue) {
+    problems.push(ownerRequiredProblem);
+    return { args, ref, owner: null };
+  }
   if (nativeIssueKeyPattern.test(legionIssue) || externalIssueRefPattern.test(legionIssue)) {
     const issue = canonicalExternalIssueRef(legionIssue);
-    return { args: { ...args, issue }, ref: null, owner: { kind: "issue", issue } };
+    return { args: { ...args, issue }, ref, owner: { kind: "issue", issue } };
   }
   if (!bareIssueNumberPattern.test(legionIssue)) {
-    throw new Error("LEGION_ISSUE must be a native issue key (e.g. LEGION-3), an external owner/repo#n reference, or a bare positive issue number");
+    problems.push("LEGION_ISSUE must be a native issue key (e.g. LEGION-3), an external owner/repo#n reference, or a bare positive issue number");
+    return { args, ref, owner: null };
   }
   const repo = await resolveCwdRepo(cwd, exec);
-  if (!repo)
-    throw new Error("issue is required; LEGION_ISSUE needs a GitHub repository in cwd");
+  if (!repo) {
+    problems.push("issue is required; LEGION_ISSUE needs a GitHub repository in cwd");
+    return { args, ref, owner: null };
+  }
   const issue = `${repo}#${legionIssue}`;
-  return { args: { ...args, issue }, ref: null, owner: { kind: "issue", issue } };
+  return { args: { ...args, issue }, ref, owner: { kind: "issue", issue } };
 }
 async function resolveArtifact(client, owner, artifactReference) {
   if (owner.kind === "project") {
@@ -15270,7 +15558,8 @@ async function resolveArtifact(client, owner, artifactReference) {
   const issue = await client.getIssue(owner.issue);
   const artifact = artifactReference === undefined || artifactReference === "spec" ? issue.artifacts.find((candidate) => candidate.primary || candidate.id === issue.primary_artifact_id) : issue.artifacts.find((candidate) => candidate.id === artifactReference || candidate.slug === artifactReference || candidate.name === artifactReference);
   if (!artifact) {
-    throw new Error(`artifact ${artifactReference ?? "spec"} was not found on issue ${issue.key}`);
+    const slugs = issue.artifacts.map((candidate) => `${candidate.slug}${candidate.primary || candidate.id === issue.primary_artifact_id ? " (primary)" : ""}`);
+    throw new Error(`artifact "${artifactReference ?? "spec"}" was not found on issue ${issue.key}; artifacts: ${slugs.length === 0 ? "none" : slugs.join(", ")}`);
   }
   return { owner, issue, artifact };
 }
@@ -15327,7 +15616,7 @@ function issueSummary(issue, events, references) {
     ...typeof references === "string" ? [`- ${references}`] : references.members.length === 0 ? ["- none"] : references.members.map(({ artifact, depth, via }) => `- ${artifact.project}/${artifact.slug} \xB7 depth ${depth} via ${via.kind} ${via.id}`),
     ...typeof references === "string" || !references.truncated ? [] : ["- more references beyond 8 hops"],
     "Events:",
-    ...events.length === 0 ? ["- none"] : events.map((event) => `- #${event.seq} ${event.type} \xB7 ${event.actor.kind} ${event.actor.id} \xB7 ${event.created_at}`)
+    ...events.length === 0 ? ["- none"] : events.map(eventLine)
   ].join(`
 `);
 }
@@ -15335,10 +15624,41 @@ function logSummary(issue, events) {
   return [
     `Key: ${issue.key}`,
     "Events:",
-    ...events.length === 0 ? ["- none"] : events.map((event) => `- #${event.seq} ${event.type} \xB7 ${event.actor.kind} ${event.actor.id} \xB7 ${event.created_at}`)
+    ...events.length === 0 ? ["- none"] : events.map(eventLine)
   ].join(`
 `);
 }
+function eventHead(event) {
+  switch (event.type) {
+    case "ask.opened":
+    case "ask.edited":
+    case "ask.resolved":
+      return textHead(event.payload.question);
+    case "ask.answered":
+      return `${textHead(event.payload.question)} -> ${textHead(askAnswerText(event.payload.answer))}`;
+    case "comment.created":
+    case "comment.edited":
+    case "comment.resolved":
+    case "comment.reopened":
+    case "suggestion.accepted":
+    case "suggestion.rejected":
+    case "message.created":
+    case "message.answered":
+      return textHead(event.payload.body);
+    case "artifact.version":
+      return textHead(`${event.payload.name} v${event.payload.version.number}${event.payload.version.summary ? `: ${event.payload.version.summary}` : ""}`);
+    case "issue.created":
+    case "issue.updated":
+    case "issue.closed":
+      return `status ${event.payload.status}`;
+    default:
+      return;
+  }
+}
+function eventLine(event) {
+  const head = eventHead(event);
+  return `- #${event.seq} ${event.type} \xB7 ${event.actor.kind} ${event.actor.id} \xB7 ${event.created_at}${head === undefined || head === "" ? "" : ` \xB7 ${head}`}`;
+}
 function childrenSummary(issue) {
   return [
     `Key: ${issue.key}`,
@@ -15473,19 +15793,29 @@ async function executeDispatchTool(input) {
       throw error;
     }
   }, { preconnect: baseFetch.preconnect });
+  const env = input.env ?? process.env;
+  const exec = input.exec ?? defaultExec;
+  const problems = [];
+  const ownerArguments = await resolveOwnerArguments(input.tool, input.args, input.cwd, env, exec, configUrl, problems);
+  const ownerMissing = issueFreeTools[input.tool] !== true && ownerArguments.owner === null;
+  const schema = toolSchema(input.tool);
+  const parsed = schema.safeParse(ownerArguments.args, { reportInput: true });
+  if (!parsed.success) {
+    const issues = parsed.error.issues.filter((issue) => !ownerMissing || !(issue.code === "invalid_type" && issue.path.length === 1 && issue.path[0] === "issue" && issue.input === undefined || issue.code === "custom" && issue.path.length === 0 && issue.message.startsWith("Exactly one of issue and project is required")));
+    problems.push(...formatZodIssues(issues, schema));
+  }
+  problems.push(...argumentProblems(input.tool, ownerArguments.args));
+  if (problems.length > 0)
+    throw new ToolInputError(input.tool, problems);
   if (input.tool === "dispatch_open_asks") {
     const sessionId = input.sessionId?.trim();
     if (!sessionId)
       throw new Error("host session id is required for dispatch_open_asks");
-    toolSchema(input.tool).parse(input.args);
     const client = new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
     const response = await client.openAsks(sessionId);
     return { text: formatOpenAsksSummary(response, configUrl), details: { ...response } };
   }
-  const env = input.env ?? process.env;
-  const exec = input.exec ?? defaultExec;
-  const ownerArguments = await resolveOwnerArguments(input.tool, input.args, input.cwd, env, exec);
-  const args = toolSchema(input.tool).parse(ownerArguments.args);
+  const args = parsed.success ? parsed.data : ownerArguments.args;
   const actor = toolActor(await resolveOrigin(env, exec, input.cwd), input);
   const client = new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
   const owner = ownerArguments.owner?.kind === "issue" ? {
@@ -15525,8 +15855,8 @@ async function executeDispatchTool(input) {
           actor
         });
         return {
-          text: `Created ${created.key}: ${created.title}`,
-          details: { issue: created.key, topic: dispatchIssueSubject(created.key, ">") }
+          text: `Created ${created.key}: ${created.title} ${notSubscribed(issueTopic(created.key))}`,
+          details: { issue: created.key }
         };
       } catch (error) {
         if (!(error instanceof DispatchServiceError) || error.code !== "POSSIBLE_DUPLICATE") {
@@ -15568,8 +15898,6 @@ async function executeDispatchTool(input) {
     }
     case "dispatch_resolve_ask": {
       const kind = stringArg(args, "kind");
-      if (kind !== "retracted" && kind !== "resolved")
-        throw new Error("kind must be retracted or resolved");
       const ask = await client.resolveAsk(stringArg(args, "ask"), {
         kind,
         reason: stringArg(args, "reason"),
@@ -15579,7 +15907,7 @@ async function executeDispatchTool(input) {
         throw new Error("resolved ask is missing its resolution");
       return {
         text: `${kind === "retracted" ? "Retracted" : "Resolved"} ask ${ask.id}: ${ask.resolution.reason}`,
-        details: await askResultDetails(client, ask)
+        details: await askOwnerDetails(client, ask)
       };
     }
     case "dispatch_ask": {
@@ -15602,9 +15930,11 @@ async function executeDispatchTool(input) {
         actor
       };
       const ask = resolved?.owner.kind === "project" ? await client.artifactAsk(resolved.artifact.id, askInput) : await client.ask(issue(), askInput);
+      const askOwner = ask.issue_key !== null ? issueTopic(ask.issue_key) : resolved === undefined ? issueTopic(issue()) : documentTopic(resolved.artifact);
       return {
-        text: `Opened ask ${ask.id}: ${ask.question}`,
-        details: await askResultDetails(client, ask, resolved)
+        text: `Asked ${ask.id} on ${askOwner.label} (urgency ${ask.urgency}): ${ask.question}
+${followsAsk(askOwner)}`,
+        details: await followedAskDetails(client, ask, resolved)
       };
     }
     case "dispatch_edit_ask": {
@@ -15621,29 +15951,17 @@ async function executeDispatchTool(input) {
       });
       return {
         text: `Ask edited: ${ask.question}`,
-        details: await askResultDetails(client, ask)
+        details: await askOwnerDetails(client, ask)
       };
     }
     case "dispatch_comment": {
       const artifactReference = optionalString(args, "artifact");
-      if (optionalString(args, "quote") !== undefined && artifactReference === undefined) {
-        throw new Error("artifact is required when quote is supplied");
-      }
       const owner = documentOwner();
       const resolved = owner.kind === "project" || artifactReference === undefined ? owner.kind === "project" ? await resolveArtifact(client, owner, artifactReference) : undefined : await resolveArtifact(client, owner, artifactReference);
       const anchored = resolved ? anchor(resolved.artifact, args) : undefined;
       const replyTo = optionalString(args, "reply_to");
       const replyToAsk = optionalString(args, "reply_to_ask");
-      if (replyTo !== undefined && replyToAsk !== undefined) {
-        throw new Error("reply_to and reply_to_ask cannot both be set");
-      }
       const requestedTurn = optionalString(args, "turn");
-      if (requestedTurn !== undefined && replyToAsk === undefined) {
-        throw new Error("turn requires reply_to_ask");
-      }
-      if (requestedTurn !== undefined && requestedTurn !== "agent" && requestedTurn !== "human") {
-        throw new Error("turn must be agent or human");
-      }
       const commentInput = {
         body: stringArg(args, "body"),
         ...anchored === undefined ? {} : { anchor: anchored },
@@ -15653,18 +15971,23 @@ async function executeDispatchTool(input) {
         actor
       };
       const comment = resolved?.owner.kind === "project" ? await client.artifactComment(resolved.artifact.id, commentInput) : await client.comment(issue(), commentInput);
-      const askState = comment.turn === null ? "" : ` (ask now waiting on ${comment.turn})`;
+      const commentOwner = resolved === undefined ? issueTopic(issue()) : resolvedTopic(resolved);
+      const commentDetails = resolved === undefined ? { issue: comment.issue_key, comment: comment.id } : writeResultDetails(resolved, { comment: comment.id });
+      if (replyToAsk !== undefined) {
+        const askState = comment.turn === null ? "" : `; ask now waiting on ${comment.turn}`;
+        return {
+          text: `Replied on ask ${replyToAsk} (comment ${comment.id}${askState}). ${followsAsk(commentOwner)}`,
+          details: {
+            ...commentDetails,
+            ask: replyToAsk,
+            follows: { ask: replyToAsk },
+            ...comment.turn === null ? {} : { ask_waiting_on: comment.turn }
+          }
+        };
+      }
       return {
-        text: `Posted comment ${comment.id}${askState}`,
-        details: resolved === undefined ? {
-          issue: comment.issue_key,
-          topic: dispatchIssueSubject(issue(), ">"),
-          comment: comment.id,
-          ...comment.turn === null ? {} : { ask_waiting_on: comment.turn }
-        } : writeResultDetails(resolved, {
-          comment: comment.id,
-          ...comment.turn === null ? {} : { ask_waiting_on: comment.turn }
-        })
+        text: `Posted comment ${comment.id} ${notSubscribed(commentOwner)}`,
+        details: commentDetails
       };
     }
     case "dispatch_suggest": {
@@ -15681,7 +16004,7 @@ async function executeDispatchTool(input) {
       };
       const comment = resolved.owner.kind === "project" ? await client.artifactSuggest(resolved.artifact.id, suggestionInput) : await client.suggest(issue(), suggestionInput);
       return {
-        text: `Posted suggestion ${comment.id}`,
+        text: `Posted suggestion ${comment.id} ${notSubscribed(resolvedTopic(resolved))}`,
         details: writeResultDetails(resolved, { comment: comment.id })
       };
     }
@@ -15695,12 +16018,8 @@ async function executeDispatchTool(input) {
       });
       const messageRef = `dispatch://${issueKey}/message/${message.id}`;
       return {
-        text: `Posted message ${message.id} (${messageRef})`,
-        details: {
-          issue: issueKey,
-          topic: dispatchIssueSubject(issueKey, ">"),
-          message: message.id
-        }
+        text: `Posted message ${message.id} (${messageRef}) ${notSubscribed(issueTopic(issueKey))}`,
+        details: { issue: issueKey, message: message.id }
       };
     }
     case "dispatch_doc_edit": {
@@ -15714,8 +16033,9 @@ async function executeDispatchTool(input) {
       });
       const retyped = ops.filter((operation) => operation.op === "retype").length;
       const versionText = edited.version === null ? "no new version" : `version ${edited.version.number}`;
+      const applied = retyped === 0 ? `Applied ${edited.applied} ops (${versionText})` : `Applied ${edited.applied} ops; retyped ${retyped} block${retyped === 1 ? "" : "s"} (${versionText})`;
       return {
-        text: retyped === 0 ? `Applied ${edited.applied} ops (${versionText})` : `Applied ${edited.applied} ops; retyped ${retyped} block${retyped === 1 ? "" : "s"} (${versionText})`,
+        text: `${applied} ${notSubscribed(resolvedTopic(resolved))}`,
         details: writeResultDetails(resolved, {
           applied: edited.applied,
           ...edited.version === null ? {} : { version: edited.version.number }
@@ -15758,7 +16078,7 @@ ${trailer.join(`
           }
         };
       }
-      const details = await askResultDetails(client, result.ask, resolved);
+      const details = await followedAskDetails(client, result.ask, resolved);
       return {
         text: `Approval requested for ${resolved.artifact.name} (document id ${resolved.artifact.id}) at version ${result.version} (ask ${result.ask.id}). The answer arrives as artifact.approved or artifact.changes_requested; an edit after approval makes it stale, so request again for the new version.`,
         details: { ...details, artifact: resolved.artifact.id, version: result.version }
@@ -15782,32 +16102,53 @@ ${trailer.join(`
       const artifactOwner = documentOwner();
       const result = artifactOwner.kind === "project" ? await client.projectArtifact(artifactOwner.project, artifactInput) : await client.artifact(issue(), artifactInput);
       const artifactRef = artifactOwner.kind === "project" ? `dispatch://${artifactOwner.project}/artifact/${result.artifact.slug}` : `dispatch://${issue()}/artifact/${result.artifact.slug}`;
+      const uploadOwner = artifactOwner.kind === "project" ? documentTopic(result.artifact) : issueTopic(issue());
       return {
-        text: `Uploaded ${result.artifact.name} as version ${result.version.number} (artifact slug ${result.artifact.slug}; ${artifactRef})`,
+        text: `Uploaded ${result.artifact.name} as version ${result.version.number} (artifact slug ${result.artifact.slug}; ${artifactRef}) ${notSubscribed(uploadOwner)}`,
         details: artifactOwner.kind === "project" ? {
           ...documentResultDetails(result.artifact),
           version: result.version.number
         } : {
           issue: issue(),
-          topic: dispatchIssueSubject(issue(), ">"),
           artifact: result.artifact.id,
           version: result.version.number
         }
       };
     }
+    case "dispatch_follow": {
+      const sessionId = input.sessionId?.trim();
+      if (!sessionId)
+        throw new Error("host session id is required for dispatch_follow");
+      const ask = askId(args);
+      const action = stringArg(args, "action");
+      if (action === "unfollow") {
+        await client.unfollowAsk(ask, sessionId, actor);
+        return { text: `Unfollowed ask ${ask}.`, details: { ask } };
+      }
+      const read = await client.getAsk(ask);
+      await client.followAsk(ask, sessionId, actor);
+      return {
+        text: `Following ask ${ask}: its answer and replies reach this session directly.`,
+        details: await followedAskDetails(client, read.ask)
+      };
+    }
     case "dispatch_read": {
       if (ownerArguments.ref?.kind === "ask") {
-        const askRead = await client.getAsk(ownerArguments.ref.id);
+        const ref = ownerArguments.ref;
+        const id = await resolveIdPrefix(input.tool, "ask", ref, async () => ref.owner.kind === "issue" ? client.listIssueAsks(ref.owner.issue) : client.getArtifactAsks((await resolveArtifact(client, ref.owner, ref.artifact)).artifact.id, "all"));
+        const askRead = await client.getAsk(id);
         return {
           text: askSummary(askRead),
-          details: ownerArguments.ref.owner.kind === "project" ? { project: ownerArguments.ref.owner.project } : { issue: ownerArguments.ref.owner.issue }
+          details: ref.owner.kind === "project" ? { project: ref.owner.project } : { issue: ref.owner.issue }
         };
       }
       if (ownerArguments.ref?.kind === "comment") {
-        const comment = await client.getComment(ownerArguments.ref.id);
+        const ref = ownerArguments.ref;
+        const id = await resolveIdPrefix(input.tool, "comment", ref, async () => ref.owner.kind === "issue" ? client.getComments(ref.owner.issue) : client.getArtifactComments((await resolveArtifact(client, ref.owner, ref.artifact)).artifact.id));
+        const comment = await client.getComment(id);
         return {
           text: commentSummary(comment),
-          details: ownerArguments.ref.owner.kind === "project" ? { project: ownerArguments.ref.owner.project } : { issue: comment.comment.issue_key }
+          details: ref.owner.kind === "project" ? { project: ref.owner.project } : { issue: comment.comment.issue_key }
         };
       }
       if (ownerArguments.ref?.kind === "message") {
@@ -15879,14 +16220,6 @@ function asObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
 }
 
-// ../envoy-client/src/dispatch-subscribe.ts
-function dispatchSubscriptionTopic(details) {
-  if (typeof details !== "object" || details === null || !("topic" in details))
-    return null;
-  const { topic } = details;
-  return typeof topic === "string" && topic.startsWith("notifications.dispatch.") ? topic : null;
-}
-
 // ../envoy-client/src/tool-contract.ts
 var DELIVERY_CONTRACT = "Delivery is at-least-once, possibly out of order across topics; use id for dedupe and at for freshness.";
 var TOPIC_GUIDE = "Topic guide (all are under notifications.): agent.<session_id> (subscribe: own inbox); role.<role> " + "(publish-to; holders claim via envoy_role_set). > matches one or more trailing tokens and does not " + "match the base subject. Envoy registers the concrete base when you subscribe to <subject>.>, so " + "the recommended default remains github.<owner>.<repo>.pr.<n>.>. Default PR subscription: " + "github.<owner>.<repo>.pr.<n>.> (it receives the quiet PR family): pr.<n> (lifecycle: " + "opened/synchronize/closed; closed carries merged, merge_commit_sha, merged_by, head_sha), " + "pr.<n>.comment, pr.<n>.review, pr.<n>.mention, pr.<n>.checks (one head-checks settlement event: " + 'passed/failed/cancelled/skipped with failing names and URLs; re-fires with superseded_settlement: "true" ' + "when new runs appear for the same head). Other GitHub: issue.<n>, issue.<n>.comment, " + "issue.<n>.mention, mention, push.branch.<name>, push.tag.<name>, workflow.<file>.<action> (only " + "runs without an associated PR); slack.<team>.<channel>.message|mention and " + "slack.<team>.<channel>.thread.<ts>.message|mention; ghostwispr.<session>.<kind>; " + "whatsapp.<phone>.<jid>.<kind>; envoy.exceptions.<original-topic>.";
@@ -15896,8 +16229,8 @@ function messageMetadataShape(schema) {
   return {
     in_reply_to: schema.string().optional(),
     supersedes: schema.string().optional(),
-    urgency: schema.enum(URGENCY_VALUES).optional(),
-    expects_reply: schema.enum(EXPECTS_REPLY_VALUES).optional(),
+    urgency: schema.enum(URGENCY_VALUES).describe("low | med | high | blocking").optional(),
+    expects_reply: schema.enum(EXPECTS_REPLY_VALUES).describe("none | optional | required").optional(),
     expires_at: schema.number({ int: true }).optional()
   };
 }
@@ -16500,24 +16833,6 @@ var server_default = async (input) => {
         }
       }
     },
-    "tool.execute.after": async (input, output) => {
-      const topic = dispatchSubscriptionTopic(output.metadata);
-      if (!topic)
-        return;
-      try {
-        await envoy.subscribe({
-          sessionID: input.sessionID,
-          directory: cwd,
-          topics: [topic],
-          port: currentPort() ?? 0,
-          title: activeSessionTitle ?? "",
-          driving: true
-        });
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        logger.warn(`[envoy-plugin] dispatch auto-subscribe failed: ${message}`);
-      }
-    },
     dispose: () => {
       clearInterval(timer);
       clearInterval(heartbeatInterval);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "1.25.0",
+  "version": "1.27.0",
   "type": "module",
   "main": "dist/src/server.js",
   "exports": {

package/skills/dispatch/SKILL.md

@@ -10,7 +10,9 @@ decide, never a log of your work. The transcript is your scratch pad; progress a
 goes through a `dispatch_*` tool.
 
 The server enforces high signal: an ask question is at most 800 characters with at most eight options; comment and message bodies are at
-most 2,000 characters; an artifact is at most 25 MiB. It refuses over-limit input; it never truncates it. GitHub threads and markers no
+most 2,000 characters; an artifact is at most 25 MiB. It refuses over-limit input with the number to trim (`question is 50 characters over
+the 800-character limit (850/800)`); it never truncates it. A tool call with several problems is refused once, every problem listed
+(`<tool> was not called: N problems`), so one corrected call lands. GitHub threads and markers no
 longer exist.
 
 ## Writing for the human
@@ -95,7 +97,7 @@ Architects create newly tracked child work with:
 dispatch_issue({ project, title, parent?, external?, spec?, force?, labels?: string[], priority?: 0 | 1 | 2 | 3 })
 ```
 `labels` are optional initial labels: Dispatch trims them, preserves their case, and removes case-insensitive duplicates. Set `priority` on creation only when the human's intent makes the bucket clear; otherwise priority remains the human's decision. It returns
-`details` `{ issue, topic }`. Use `dispatch_issue` only to create an issue; never use it to park a question. When `spec` is supplied,
+`details` `{ issue }`; creating an issue does not subscribe you to it (see [Following](#following)). Use `dispatch_issue` only to create an issue; never use it to park a question. When `spec` is supplied,
 follow [Writing a spec](#writing-a-spec).
 
 ## Search first
@@ -129,7 +131,7 @@ dispatch_ask({
   anchor?: { artifact, quote, occurrence? },
 })
 ```
-It returns `details` `{ issue, topic, ask }` for an issue or `{ project, artifact, document, topic, ask }` for a project document.
+It returns `details` `{ issue, ask, follows: { ask } }` for an issue or `{ project, artifact, document, ask, follows: { ask } }` for a project document: you follow the ask you opened (see [Following](#following)).
 
 References belong in the question text; `ref` is sugar that appends its `dispatch://` value to the question as a rendered link.
 
@@ -246,7 +248,7 @@ It returns live or versioned markdown with open marks. `issue` with an omitted `
 ```ts
 dispatch_doc_edit({ issue?, project?, artifact, ops, summary? })
 ```
-It returns issue or project-document owner details plus `applied`, optional `version`, and its write `topic`. `ops` is an array of this
+It returns issue or project-document owner details plus `applied` and optional `version`. `ops` is an array of this
 exact `EditOp` shape:
 
 ```ts
@@ -273,7 +275,8 @@ within one textblock; split changes that span separate blocks into separate oper
 insert anchor is a quote, `"start"`, `"end"`, or `"heading:Title"`. Ordinary inserts create a sibling block before or after the quote or
 heading's enclosing document block; `"start"` and `"end"` select the document edges. At a table-cell quote, a body-row fragment (no
 header or delimiter rows) extends that table before or after the matched row instead; short rows are padded, wider rows are rejected,
-and deleting a cell's quoted text removes only that text.
+and deleting a cell's quoted text removes only that text. A `find` or quote anchor tolerates inline Markdown (`**bold**`, `` `code` ``)
+and a leading `# ` selects a heading by its text; a miss names the three nearest blocks so the next quote lands.
 
 Use `replace` for inline continuation. Use zero-based `occurrence` for a repeated target; re-read a missing or ambiguous target before
 retrying. Pass `summary` to name the version when recording a decision.
@@ -321,7 +324,8 @@ Add feedback with:
 dispatch_comment({ issue?, project?, artifact?, ref?, quote?, occurrence?, body, reply_to?, reply_to_ask?, turn? })
 ```
 
-It returns issue or project-document owner details plus `comment` and, for writes, `topic`.
+It returns issue or project-document owner details plus `comment`; a `reply_to_ask` reply also returns `ask` and `follows: { ask }`,
+because replying to an ask makes you one of its followers (see [Following](#following)).
 `ref` names the owner (an issue or project-document reference) in place of `issue`/`project`.
 `quote` requires `artifact`; its anchor is pinned to the containing block while retaining the quote
 for display. Omit both for a floating issue comment. A reply (`reply_to`/`reply_to_ask`) takes no
@@ -339,7 +343,7 @@ Propose an exact replacement instead of describing it:
 dispatch_suggest({ issue?, project?, artifact, ref?, quote, replace_with, body?, occurrence? })
 ```
 
-It returns issue or project-document owner details plus `comment` and its write `topic`. A human accepts or rejects a suggestion.
+It returns issue or project-document owner details plus `comment`. A human accepts or rejects a suggestion.
 Errors: `TARGET_AMBIGUOUS` (add `occurrence`), `TARGET_NOT_FOUND` (re-read first), `INVALID_ANCHOR`/`ANCHOR_MISSING`/`ANCHOR_ORPHANED`
 (bad, unwritten, or stale quote), `INVALID_MARKDOWN`/`DOC_SCHEMA` (malformed content), `CAP_EXCEEDED`, `ISSUE_CLOSED`.
 
@@ -358,8 +362,8 @@ dispatch_artifact({ issue?, project?, name: "load-test-results.md", content: "#
 ```
 
 Exactly one of `issue` and `project` is required. A project upload creates an unlinked project document; it must not include `artifact`.
-Exactly one of `path` and `content` is required. It returns issue or project-document owner details plus `artifact`, `version`, and its
-write `topic`. Uploading the same `name` creates its next version — so uploading `spec.md` **replaces the issue's own specification**
+Exactly one of `path` and `content` is required. It returns issue or project-document owner details plus `artifact` and `version`.
+Uploading the same `name` creates its next version — so uploading `spec.md` **replaces the issue's own specification**
 with your text. Never do that: the spec is edited in place with `dispatch_doc_edit` (see [The Spec](#the-spec)). Address an existing
 artifact by the slug shown in the upload result or by its filename, and a project document by its artifact id, slug, or filename; the
 slug also arrives on `artifact.created` events.
@@ -393,14 +397,14 @@ pull request is where it is summarised. One message that a human reads beats ten
 dispatch_message({ issue, body })
 ```
 
-It returns `details` `{ issue, topic, message }`. `body` is capped at 2,000 characters. A message is not a decision
+It returns `details` `{ issue, message }`. `body` is capped at 2,000 characters. A message is not a decision
 (`dispatch_ask`) or document feedback (`dispatch_comment`), and it does not wake anyone unless the issue is routed.
 
 ### Targeted agent messages
 
 A human — or any bearer caller over HTTP, such as a test rig — can target the issue message at a
 live Envoy session or role as **BTW**, **Aside**, or **Steer**. The incoming Dispatch frame names
-the issue and includes a `reply_with` instruction; reply on the same open issue with the existing
+the issue and includes a `reply_with` hint (`{ tool, args }`, ready to issue on any host); reply on the same open issue with the existing
 tool, never a new targeted send:
 
 ```ts
@@ -420,13 +424,31 @@ through Envoy or the hub. A bearer that targets over HTTP names its own session
 target only a session that advertises the mode you want. Sending to a session with no issue
 (`POST /api/v1/agents/{session_id}/messages`) stays human-only.
 
+## Following
+
+An ask has followers: every session that wrote to it — the session that opened it and every session that replied with
+`dispatch_comment({ reply_to_ask })` — plus any session a human adds from the ask card. The ask's answer, edits, resolution, and
+every reply on it reach each follower's own agent topic directly, whether or not the writer was a human and whatever the issue's
+route. The tool result says so (`You follow this ask: its answer and replies reach you directly.`) and carries `details.follows.ask`;
+the host tells you once per ask. Leave a thread you no longer need, or rejoin one, with:
+
+```ts
+dispatch_follow({ ask, action: "follow" | "unfollow" })
+```
+
+`ask` is the full ask id or a `dispatch://KEY/ask/<id>` reference. A human may also remove you from the ask card; either way you are
+told with an `ask.follower_removed` notice, and a human adding you arrives as `ask.follower_added`.
+
+No write subscribes you to an issue or document. Following covers your own asks and the threads you joined; everything else on the
+owner — other sessions' asks, comments, messages, status changes — reaches you only if you subscribe to the owner topic yourself.
+Every write result names that line: `envoy_subscribe notifications.dispatch.issue.<KEY>.>` for an issue,
+`envoy_subscribe notifications.dispatch.document.<PROJECT>.<SLUG>.>` for a project document. The owner topic carries every Dispatch
+event; `notify` only controls agent wake and routed delivery. A human may unsubscribe you from the issue or document header; you
+are told with a `subscription.removed` notice when that happens.
+
 ## What comes back
 
-A write result's `details.topic` subscribes the host to its owner, and the first such subscription on an issue or document also tells
-you so (an already-subscribed write stays quiet — no repeat notice). Issue writes use `notifications.dispatch.issue.<KEY>.>`;
-project-document writes use `notifications.dispatch.document.<PROJECT>.<SLUG>.>`. The owner topic carries every Dispatch event; `notify`
-only controls agent wake and routed delivery. A human may unsubscribe you from the issue or document header; you are told with a
-`subscription.removed` notice when that happens. After a restart, catch up with:
+After a restart, catch up with:
 
 ```ts
 dispatch_read({ issue?, project?, artifact?, ref? })
@@ -458,7 +480,11 @@ dispatch://PROJECT/artifact/<document-ref>/ask/<id>
 dispatch://PROJECT/artifact/<document-ref>/comment/<id>
 ```
 
-A bare UUID or `KEY#seq` is not a reference; the `dispatch://` form is what Dispatch links and records.
+A bare UUID or `KEY#seq` is not a reference; the `dispatch://` form is what Dispatch links and records. `dispatch_read` also
+accepts the dashboard URL of an issue, spec, artifact, ask, comment, or project document on the configured server (it maps to the
+`dispatch://` form above), and an ask or comment id may be a unique prefix of at least 8 hex characters; a message id is always the
+full uuid. A non-uuid id on `GET /asks/{id}`, `/comments/{id}`, or `/issues/{key}/messages/{id}` is a 400 `ASK_ID_INPUT` /
+`COMMENT_ID_INPUT` / `MESSAGE_ID_INPUT`, never a 500.
 
 ## Before / after
 

package/skills/envoy/SKILL.md

@@ -47,8 +47,17 @@ envoy:
   expects_reply: required
   re: agent-message-1
   supersedes: agent-message-0
-  reply_with: "envoy_send(session_id=\"01a0bbbb-cccc-7ddd-eeee-0123456789ab\", message=\"...\")"
-  reply_role: "envoy_publish(topic=\"notifications.role.legion-reviewer\", message=\"...\")"
+  reply_with:
+    tool: envoy_send
+    args:
+      session_id: 01a0bbbb-cccc-7ddd-eeee-0123456789ab
+      in_reply_to: agent-message-2
+      message: ...
+  reply_role:
+    tool: envoy_publish
+    args:
+      topic: notifications.role.legion-reviewer
+      message: ...
   summary: Deployment needs confirmation.
   message: "Confirm the listener health check passed.\n\nThen publish the release."
   note: body names session 01a0cccc-dddd-7eee-ffff-0123456789ab; the sender is 01a0bbbb-cccc-7ddd-eeee-0123456789ab
@@ -62,7 +71,10 @@ envoy:
 - `by` is the expiry deadline, when the sender supplied one.
 - `urgency` is the sender's priority classification.
 - `expects_reply` states whether a reply is `none`, `optional`, or `required`.
-- `re` names the delivery this message replies to.
+- `re` names the delivery this message replies to. A Dispatch frame names it as a `dispatch://`
+  ref — the ask (`dispatch://KEY/ask/<id>`, or `dispatch://PROJECT/artifact/<slug>/ask/<id>` for a
+  document ask) or the message (`dispatch://KEY/message/<id>`) — never the quoted text; the
+  question head, when there is one, is `dispatch.question`.
 - `supersedes` names an earlier delivery this one replaces.
 - `reply_with` is the direct-reply call for the sender.
 - `reply_role` is the role-publish reply call when the sender has a role.

package/src/server.ts

@@ -5,7 +5,6 @@ import { agentSubject, dispatchToolSpecs, zodSchemaApi } from "@legion/contracts
 import { envoyDefaultsFromEnvironment } from "@legion/envoy-client/defaults";
 import { resolveDispatchConfig } from "@legion/envoy-client/dispatch-config";
 import { executeDispatchTool } from "@legion/envoy-client/dispatch-execute";
-import { dispatchSubscriptionTopic } from "@legion/envoy-client/dispatch-subscribe";
 import { machineID } from "@legion/envoy-client/machine";
 import {
   envoyToolSpecs,
@@ -269,29 +268,6 @@ export default async (input: { serverUrl: URL }) => {
         }
       }
     },
-    "tool.execute.after": async (
-      input: { tool: string; sessionID: string; callID: string; args: unknown },
-      output: { title: string; output: string; metadata: unknown }
-    ) => {
-      // Native Dispatch tools return `DispatchToolResult.details` in OpenCode
-      // output metadata, so only mutations with a Dispatch topic are followed.
-      // Best-effort — a subscribe failure must never surface to the model.
-      const topic = dispatchSubscriptionTopic(output.metadata);
-      if (!topic) return;
-      try {
-        await envoy.subscribe({
-          sessionID: input.sessionID,
-          directory: cwd,
-          topics: [topic],
-          port: currentPort() ?? 0,
-          title: activeSessionTitle ?? "",
-          driving: true,
-        });
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        logger.warn(`[envoy-plugin] dispatch auto-subscribe failed: ${message}`);
-      }
-    },
     // Cleanup hook (used by tests; production relies on process 'exit').
     dispose: () => {
       clearInterval(timer);