@sjawhar/pi-legion-envoy 1.36.0 → 1.37.0

package/README.md

@@ -85,10 +85,10 @@ extension files it does not contain.
 
 ## Native Dispatch tools
 
-The extension registers twelve native Dispatch tools: `dispatch_issue`, `dispatch_ask`, `dispatch_edit_ask`,
-`dispatch_resolve_ask`, `dispatch_comment`, `dispatch_suggest`, `dispatch_message`,
-`dispatch_doc_edit`, `dispatch_doc_read`, `dispatch_artifact`, `dispatch_read`, and
-`dispatch_search`, when Dispatch configuration resolves both a base URL and bearer token.
+The extension registers fifteen native Dispatch tools: `dispatch_issue`, `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`, and `dispatch_open_asks`, when Dispatch configuration resolves both a base URL and bearer token.
 
 Configure the shared `envoy.json` with:
 
@@ -112,21 +112,23 @@ whose trimmed contents are the token — how the Legion daemon delivers it to a
 pane) wins over every other token source and never falls back when unreadable.
 Omitting `dispatch.serverUrl` while `dispatch.enabled` is true targets
 `http://localhost:8766`, the Go server's listen address. Invalid configuration,
-an invalid URL, or an empty token leaves the twelve tools unavailable and
+an invalid URL, or an empty token leaves the fifteen tools unavailable and
 reports the source of the error.
 
 Owner-scoped calls use either an issue (a native `KEY` or external `owner/repo#n` reference) or
 an unlinked project document (`project` plus its `artifact` slug). A Legion session may omit
 `issue` when `LEGION_ISSUE` identifies its root issue and its working directory resolves to a
 repository. `dispatch_doc_read` and `dispatch_read` also accept `dispatch://` references,
-including `dispatch://PROJECT/artifact/<slug>`. `dispatch_search` needs only its query and
-returns no subscription topic. `dispatch_edit_ask` and `dispatch_resolve_ask` instead identify
-an existing ask with `ask`. Every mutation result carries `details.topic`: issue writes use
-`notifications.dispatch.issue.<KEY>.>` and project-document writes use
-`notifications.dispatch.document.<PROJECT>.<SLUG>.>`. The extension's `tool_result` hook
-subscribes to that exact topic, then registers the session so retained events arrive as Pi
-steering. `dispatch_doc_read` and `dispatch_read` return owner details without a subscription
-topic.
+including `dispatch://PROJECT/artifact/<slug>`. `dispatch_search` needs only its query.
+`dispatch_edit_ask`, `dispatch_resolve_ask`, and `dispatch_follow` instead identify an existing
+ask with `ask`. No result carries a subscription topic: opening an ask or replying to one with
+`dispatch_comment({ reply_to_ask })` makes the session a follower of that ask (its answer and
+replies reach the session directly, server-side), the result carries `details.follows.ask`, and
+the extension's `tool_result` hook tells the model so once per ask. Whole-issue or
+whole-document subscription is the model's own `envoy_subscribe` of the topic every write
+result names (`notifications.dispatch.issue.<KEY>.>` or
+`notifications.dispatch.document.<PROJECT>.<SLUG>.>`). `dispatch_doc_read` and
+`dispatch_read` return owner details only.
 
 The shared contract supplies the model-facing schemas and descriptions. The
 `dispatch` skill describes when to use each operation for issues, asks, review

package/dist/envoy.js

@@ -29779,6 +29779,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;", "<"],
@@ -29944,6 +29949,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}`,
@@ -31119,6 +31133,9 @@ function askAnswerText(answer) {
 // ../envoy-client/src/delivery.ts
 var KNOWN_SOURCES = EnvelopeSchema.shape.source.enum;
 var FOREIGN_SESSION_ID = /\b01a0[0-9a-f]{4}-[0-9a-f]{4}-7[0-9a-f]{3}-[0-9a-f]{4}-[0-9a-f]{12}\b/g;
+var AskAuthorPayloadSchema = object({
+  author: object({ kind: string2(), id: string2() }).passthrough()
+});
 var InboundSenderSchema = object({
   session_id: string2().optional(),
   machine: string2().optional(),
@@ -31381,6 +31398,7 @@ function renderInbound(raw, sessionID, subject) {
   let rejectedDelivery;
   let malformedDelivery = false;
   let inReplyTo = envelope.in_reply_to;
+  let askAuthor;
   const dispatchRendered = envelope.source === "dispatch" && envelope.payload !== undefined;
   if (envelope.source === "dispatch") {
     if (envelope.payload === undefined) {
@@ -31406,8 +31424,28 @@ function renderInbound(raw, sessionID, subject) {
             envelope
           };
         }
+        if (frame.event.type === "ask.follower_added" || frame.event.type === "ask.follower_removed") {
+          const follower = AskFollowerEventPayloadSchema.safeParse(frame.event.payload);
+          if (!follower.success || follower.data.session_id !== sessionID) {
+            return { skip: true, content: "", envelope };
+          }
+          const who = follower.data.by?.id ?? "someone";
+          const owner = dispatchOwner(frame.event, subject ?? envelope.topic);
+          const ask = follower.data.ask_id ?? "?";
+          return {
+            skip: false,
+            content: frame.event.type === "ask.follower_added" ? `Now following ask ${ask} on ${owner} (added by ${who}): its answer and replies reach you directly; dispatch_follow unfollow to stop.` : `No longer following ask ${ask} on ${owner} (removed by ${who}).`,
+            envelope
+          };
+        }
         const answered = dispatchAskAnswer(frame.event);
         const question = answered?.question ?? dispatchAskQuestion(frame.event);
+        if (frame.event.type.startsWith("ask.")) {
+          const asked = AskAuthorPayloadSchema.safeParse(frame.event.payload);
+          if (asked.success && asked.data.author.kind === "session") {
+            askAuthor = asked.data.author.id;
+          }
+        }
         if (inReplyTo !== undefined) {
           inReplyTo = dispatchReplyRef(frame.event, subject ?? envelope.topic, inReplyTo);
         }
@@ -31468,7 +31506,7 @@ function renderInbound(raw, sessionID, subject) {
 ${envelope.payload ?? ""}`;
   let foreignSession;
   for (const match of body.matchAll(FOREIGN_SESSION_ID)) {
-    if (match[0] !== envelope.source_session && match[0] !== sessionID) {
+    if (match[0] !== envelope.source_session && match[0] !== sessionID && match[0] !== askAuthor) {
       foreignSession = match[0];
       break;
     }
@@ -31921,6 +31959,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]);
   }
@@ -32154,12 +32198,33 @@ function formatZodIssues(issues, schema) {
 }
 
 // ../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) {
@@ -32168,19 +32233,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");
@@ -32188,6 +32245,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]*$/;
@@ -32195,6 +32255,7 @@ var issueFreeTools = {
   dispatch_issue: true,
   dispatch_edit_ask: true,
   dispatch_resolve_ask: true,
+  dispatch_follow: true,
   dispatch_search: true,
   dispatch_open_asks: true
 };
@@ -32857,8 +32918,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") {
@@ -32909,7 +32970,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": {
@@ -32932,9 +32993,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": {
@@ -32951,7 +33014,7 @@ async function executeDispatchTool(input) {
       });
       return {
         text: `Ask edited: ${ask.question}`,
-        details: await askResultDetails(client, ask)
+        details: await askOwnerDetails(client, ask)
       };
     }
     case "dispatch_comment": {
@@ -32971,18 +33034,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": {
@@ -32999,7 +33067,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 })
       };
     }
@@ -33013,12 +33081,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": {
@@ -33032,8 +33096,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 }
@@ -33076,7 +33141,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 }
@@ -33100,19 +33165,36 @@ ${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 ref = ownerArguments.ref;
@@ -33202,25 +33284,30 @@ function asObject(value) {
 }
 
 // ../envoy-client/src/dispatch-subscribe.ts
-function dispatchSubscriptionTopic(details) {
-  if (typeof details !== "object" || details === null || !("topic" in details))
+function dispatchFollowNotice(details) {
+  if (typeof details !== "object" || details === null)
+    return null;
+  const { follows, issue, document } = details;
+  if (typeof follows !== "object" || follows === null)
+    return null;
+  const { ask } = follows;
+  if (typeof ask !== "string" || ask === "")
+    return null;
+  let owner;
+  if (typeof issue === "string" && issue !== "") {
+    owner = { label: issue, topic: dispatchIssueSubject(issue, ">") };
+  } else if (typeof document === "string") {
+    const [project, slug] = document.split("/", 2);
+    if (!project || !slug)
+      return null;
+    owner = { label: document, topic: dispatchDocumentSubject(project, slug, ">") };
+  } else {
     return null;
-  const { topic } = details;
-  return typeof topic === "string" && topic.startsWith("notifications.dispatch.") ? topic : null;
-}
-function dispatchTopicLabel(topic) {
-  if (topic.startsWith(DISPATCH_ISSUE_TOPIC_PREFIX)) {
-    const [key] = topic.slice(DISPATCH_ISSUE_TOPIC_PREFIX.length).split(".", 2);
-    if (key !== undefined && key !== "")
-      return key;
-  }
-  if (topic.startsWith(DISPATCH_DOCUMENT_TOPIC_PREFIX)) {
-    const [project, slug] = topic.slice(DISPATCH_DOCUMENT_TOPIC_PREFIX.length).split(".", 3);
-    if (project !== undefined && project !== "" && slug !== undefined && slug !== "") {
-      return `${project}/${slug}`;
-    }
   }
-  return topic;
+  return {
+    ask,
+    text: `Following ask ${ask} on ${owner.label}: its answer and replies reach you directly (dispatch_follow unfollow to stop). For every event on ${owner.label}: envoy_subscribe ${owner.topic}.`
+  };
 }
 function subscriptionRemovedTopics(raw, sessionID) {
   let envelope;
@@ -34326,26 +34413,15 @@ ${formatOpenAsksSummary(snapshot, currentDispatchConfig().url)}`,
       };
     }
   });
+  const announcedFollows = new Set;
   pi.on("tool_result", async (event) => {
     if (event.isError)
       return;
-    const topic = dispatchSubscriptionTopic(event.details);
-    if (topic === null)
+    const notice = dispatchFollowNotice(event.details);
+    if (notice === null || announcedFollows.has(notice.ask))
       return;
-    try {
-      const isNew = await subscribe(topic);
-      if (isNew)
-        await registerSession();
-      if (isNew) {
-        pi.sendMessage({
-          customType: "envoy-message",
-          content: `Subscribed to ${dispatchTopicLabel(topic)} (every event on this issue reaches you; envoy_unsubscribe ${topic} to stop).`,
-          display: true
-        }, { deliverAs: "steer", triggerTurn: false });
-      }
-    } catch (error) {
-      activeSessionContext?.ui.notify(`envoy: dispatch reply auto-subscribe failed (${messageFor(error)}); run envoy_subscribe ${topic}`, "warning");
-    }
+    announcedFollows.add(notice.ask);
+    pi.sendMessage({ customType: "envoy-message", content: notice.text, display: true }, { deliverAs: "steer", triggerTurn: false });
   });
   async function execute(operation, rawParameters) {
     try {

package/dist/legion.js

@@ -29053,6 +29053,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;", "<"],
@@ -29218,6 +29223,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}`,

package/dist/skills/dispatch/SKILL.md

@@ -97,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
@@ -131,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.
 
@@ -248,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
@@ -324,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
@@ -342,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`.
 
@@ -361,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.
@@ -396,7 +397,7 @@ 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
@@ -423,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? })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-legion-envoy",
-  "version": "1.36.0",
+  "version": "1.37.0",
   "type": "module",
   "omp": {
     "extensions": [