@sjawhar/pi-legion-envoy 1.35.1 → 1.36.0

package/dist/envoy.js

@@ -29903,7 +29903,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({
@@ -29955,7 +29955,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()
     }),
@@ -29987,7 +29987,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(),
@@ -29995,12 +29995,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()
@@ -30504,6 +30504,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 {
@@ -30511,8 +30514,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 = {}) => {
@@ -31091,6 +31098,24 @@ function resolveOptions(options) {
   };
 }
 
+// ../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/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;
@@ -31147,7 +31172,14 @@ function senderLabel(envelope) {
 function replyWith(envelope) {
   if (envelope.source !== "agent" || envelope.source_session === undefined)
     return;
-  return `envoy_send(session_id="${envelope.source_session}", message="...")`;
+  return {
+    tool: "envoy_send",
+    args: {
+      session_id: envelope.source_session,
+      ...envelope.event_id === undefined ? {} : { in_reply_to: envelope.event_id },
+      message: "..."
+    }
+  };
 }
 var DISPATCH_PAYLOAD_SCHEMAS = {
   "issue.created": IssueEventPayloadSchema,
@@ -31170,15 +31202,18 @@ var DISPATCH_PAYLOAD_SCHEMAS = {
   "message.answered": MessageEventPayloadSchema,
   "child.status": ChildStatusEventPayloadSchema
 };
+function topicDocument(topic) {
+  if (topic?.startsWith(DISPATCH_DOCUMENT_TOPIC_PREFIX) !== true)
+    return;
+  const [project, slug] = topic.slice(DISPATCH_DOCUMENT_TOPIC_PREFIX.length).split(".", 3);
+  return project !== undefined && project !== "" && slug !== undefined && slug !== "" ? { project, slug } : undefined;
+}
 function dispatchOwner(event, topic) {
   if (event.issue_key !== null)
     return event.issue_key;
-  if (topic?.startsWith(DISPATCH_DOCUMENT_TOPIC_PREFIX) === true) {
-    const [project, slug] = topic.slice(DISPATCH_DOCUMENT_TOPIC_PREFIX.length).split(".", 3);
-    if (project !== undefined && project !== "" && slug !== undefined && slug !== "") {
-      return `${project} / ${slug}`;
-    }
-  }
+  const document = topicDocument(topic);
+  if (document !== undefined)
+    return `${document.project} / ${document.slug}`;
   return event.artifact_id ?? "unknown";
 }
 function dispatchCommentReplyWith(event, topic) {
@@ -31189,9 +31224,12 @@ function dispatchCommentReplyWith(event, topic) {
     return;
   const reply = comment.data.ask_id;
   const thread = reply === undefined || reply === null || reply === "" ? "reply_to" : "reply_to_ask";
-  const threadID = thread === "reply_to" ? comment.data.id : reply;
+  const threadID = thread === "reply_to" ? comment.data.id : String(reply);
   if (event.issue_key !== null) {
-    return `dispatch_comment(issue="${event.issue_key}", ${thread}="${threadID}", body="...")`;
+    return {
+      tool: "dispatch_comment",
+      args: { issue: event.issue_key, [thread]: threadID, body: "..." }
+    };
   }
   let project = comment.data.project_key;
   let artifact = comment.data.artifact_slug;
@@ -31200,7 +31238,21 @@ function dispatchCommentReplyWith(event, topic) {
   }
   if (project === undefined || project === "" || artifact === undefined || artifact === "")
     return;
-  return `dispatch_comment(project="${project}", artifact="${artifact}", ${thread}="${threadID}", body="...")`;
+  return {
+    tool: "dispatch_comment",
+    args: { project, artifact, [thread]: threadID, body: "..." }
+  };
+}
+function dispatchAskAnswer(event) {
+  if (event.type !== "ask.answered")
+    return;
+  const ask = AskEventPayloadSchema.safeParse(event.payload);
+  if (!ask.success)
+    return;
+  return {
+    question: textHead(ask.data.question ?? ""),
+    answer: askAnswerText(ask.data.answer)
+  };
 }
 function dispatchPayload(event) {
   const schema = DISPATCH_PAYLOAD_SCHEMAS[event.type];
@@ -31213,13 +31265,33 @@ function dispatchAskQuestion(event) {
   if (event.type !== "comment.created")
     return;
   const parsed = CommentEventPayloadSchema.safeParse(event.payload);
-  return parsed.success && parsed.data.ask_question !== "" ? parsed.data.ask_question : undefined;
-}
-function dispatchMessageReplyPreview(event) {
-  if (event.type !== "message.created")
-    return;
-  const parsed = MessageEventPayloadSchema.safeParse(event.payload);
-  return parsed.success && parsed.data.reply_body !== undefined && parsed.data.reply_body !== "" ? parsed.data.reply_body : undefined;
+  return parsed.success && parsed.data.ask_question !== undefined && parsed.data.ask_question !== "" ? textHead(parsed.data.ask_question) : undefined;
+}
+function dispatchReplyRef(event, topic, inReplyTo) {
+  let kind;
+  let document = topicDocument(topic);
+  if (event.type.startsWith("ask.")) {
+    kind = "ask";
+  } else if (event.type.startsWith("message.")) {
+    kind = "message";
+  } else if (event.type === "comment.created") {
+    const comment = CommentEventPayloadSchema.safeParse(event.payload);
+    if (!comment.success || comment.data.ask_id === undefined || comment.data.ask_id === null) {
+      return inReplyTo;
+    }
+    kind = "ask";
+    const { project_key: project, artifact_slug: slug } = comment.data;
+    if (project !== undefined && project !== "" && slug !== undefined && slug !== "") {
+      document = { project, slug };
+    }
+  } else {
+    return inReplyTo;
+  }
+  if (event.issue_key !== null)
+    return `dispatch://${event.issue_key}/${kind}/${inReplyTo}`;
+  if (document === undefined)
+    return inReplyTo;
+  return `dispatch://${document.project}/artifact/${document.slug}/${kind}/${inReplyTo}`;
 }
 function isObject2(value) {
   return typeof value === "object" && value !== null;
@@ -31308,8 +31380,7 @@ function renderInbound(raw, sessionID, subject) {
   let delivery;
   let rejectedDelivery;
   let malformedDelivery = false;
-  let askQuestion;
-  let messageReplyPreview;
+  let inReplyTo = envelope.in_reply_to;
   const dispatchRendered = envelope.source === "dispatch" && envelope.payload !== undefined;
   if (envelope.source === "dispatch") {
     if (envelope.payload === undefined) {
@@ -31335,8 +31406,11 @@ function renderInbound(raw, sessionID, subject) {
             envelope
           };
         }
-        askQuestion = dispatchAskQuestion(frame.event);
-        messageReplyPreview = dispatchMessageReplyPreview(frame.event);
+        const answered = dispatchAskAnswer(frame.event);
+        const question = answered?.question ?? dispatchAskQuestion(frame.event);
+        if (inReplyTo !== undefined) {
+          inReplyTo = dispatchReplyRef(frame.event, subject ?? envelope.topic, inReplyTo);
+        }
         dispatchReply = dispatchCommentReplyWith(frame.event, subject ?? envelope.topic);
         if (frame.event.type === "message.created") {
           const message = MessageEventPayloadSchema.safeParse(frame.event.payload);
@@ -31350,7 +31424,10 @@ function renderInbound(raw, sessionID, subject) {
               body: message.data.body ?? envelope.payload_summary ?? ""
             };
             if (frame.event.issue_key !== null) {
-              dispatchReply = `dispatch_message(issue="${frame.event.issue_key}", in_reply_to="${message.data.id}", body="...")`;
+              dispatchReply = {
+                tool: "dispatch_message",
+                args: { issue: frame.event.issue_key, in_reply_to: message.data.id, body: "..." }
+              };
             }
           }
         }
@@ -31364,6 +31441,8 @@ function renderInbound(raw, sessionID, subject) {
           } : { issue_key: frame.event.issue_key },
           type: frame.event.type,
           actor: frame.event.actor,
+          ...question === undefined ? {} : { question },
+          ...answered === undefined ? {} : { answer: answered.answer },
           payload: dispatchPayload(frame.event)
         };
         dispatchActor = frame.event.actor;
@@ -31410,11 +31489,14 @@ ${envelope.payload ?? ""}`;
     ...envelope.expires_at === undefined ? {} : { by: inboundTimestamp(envelope.expires_at) },
     ...envelope.urgency === undefined ? {} : { urgency: envelope.urgency },
     ...envelope.expects_reply === undefined ? {} : { expects_reply: envelope.expects_reply },
-    ...envelope.in_reply_to === undefined ? {} : { re: askQuestion ?? messageReplyPreview ?? envelope.in_reply_to },
+    ...inReplyTo === undefined ? {} : { re: inReplyTo },
     ...envelope.supersedes === undefined ? {} : { supersedes: envelope.supersedes },
     ...reply === undefined ? {} : { reply_with: reply },
     ...role === undefined ? {} : {
-      reply_role: `envoy_publish(topic="notifications.role.${role}", message="...")`
+      reply_role: {
+        tool: "envoy_publish",
+        args: { topic: `notifications.role.${role}`, message: "..." }
+      }
     },
     ...dispatchRendered ? { dispatch: dispatchEvent } : {
       ...summaryIsHead ? {} : { summary: payloadSummary },
@@ -31760,6 +31842,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 });
   }
@@ -31958,6 +32043,116 @@ 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 documentResultDetails(artifact) {
   return {
@@ -32052,23 +32247,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)\/([^/]+))?$/);
@@ -32090,7 +32281,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\/([^/]+))?$/);
@@ -32122,60 +32314,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,
@@ -32187,7 +32490,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,
@@ -32208,20 +32511,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") {
@@ -32252,7 +32560,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 };
 }
@@ -32309,7 +32618,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(`
 `);
 }
@@ -32317,10 +32626,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}`,
@@ -32455,19 +32795,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" ? {
@@ -32550,8 +32900,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"),
@@ -32608,24 +32956,12 @@ async function executeDispatchTool(input) {
     }
     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 },
@@ -32779,17 +33115,21 @@ ${trailer.join(`
     }
     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") {
@@ -32918,8 +33258,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()
   };
 }
@@ -33029,6 +33369,17 @@ var envoyToolSpecs = [
     requiresSubscriptionCapability: false
   }
 ];
+function parseEnvoyToolArguments(operation, parameters) {
+  const spec = envoyToolSpecs.find((candidate) => candidate.operation === operation);
+  if (spec === undefined)
+    throw new Error(`missing Envoy tool specification for ${operation}`);
+  const schema = object(spec.arguments(zodSchemaApi(exports_external))).strict();
+  const parsed = schema.safeParse(parameters, { reportInput: true });
+  if (!parsed.success) {
+    throw new ToolInputError(spec.name, formatZodIssues(parsed.error.issues, schema));
+  }
+  return parsed.data;
+}
 
 // ../envoy-client/src/transport.ts
 var DEFAULT_TIMEOUT_MS = 5000;
@@ -33912,6 +34263,7 @@ function envoyExtension(pi) {
       label: spec.name,
       description: spec.description,
       parameters: schemaFor(pi, spec.operation),
+      lenientArgValidation: true,
       execute: async (_id, parameters) => execute(spec.operation, parameters)
     });
   }
@@ -33922,6 +34274,7 @@ function envoyExtension(pi) {
         label: spec.name,
         description: spec.description,
         parameters: dispatchToolSchema(spec, zodSchemaApi(pi.zod)),
+        lenientArgValidation: true,
         execute: async (_id, params, signal, _onUpdate, context) => {
           try {
             const result = await executeDispatchTool({
@@ -33994,8 +34347,9 @@ ${formatOpenAsksSummary(snapshot, currentDispatchConfig().url)}`,
       activeSessionContext?.ui.notify(`envoy: dispatch reply auto-subscribe failed (${messageFor(error)}); run envoy_subscribe ${topic}`, "warning");
     }
   });
-  async function execute(operation, parameters) {
+  async function execute(operation, rawParameters) {
     try {
+      const parameters = parseEnvoyToolArguments(operation, rawParameters);
       switch (operation) {
         case EnvoyToolOperation.subscribe: {
           const added = [];

package/dist/legion.js

@@ -29177,7 +29177,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({
@@ -29229,7 +29229,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()
     }),
@@ -29261,7 +29261,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(),
@@ -29269,12 +29269,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()
@@ -29778,6 +29778,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 {
@@ -29785,8 +29788,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 = {}) => {

package/dist/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
@@ -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.
@@ -400,7 +403,7 @@ It returns `details` `{ issue, topic, message }`. `body` is capped at 2,000 char
 
 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
@@ -458,7 +461,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/dist/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/package.json

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