@ezmodo/mcp-server 0.19.1 → 0.20.1

package/config/endpoint-map.js

@@ -40,12 +40,18 @@ export const ENDPOINT_MAP = {
   'mcpProposePlanChange': { route: 'mcp/v1/epics/proposals', method: 'POST' },
   'mcpReviewPlanProposal': { route: 'mcp/v1/epics/proposals/review', method: 'POST' },
   'mcpAddEpicComment': { route: 'mcp/v1/epics/comments', method: 'POST' },
+  // Editors (E-259 #2802): who the owner lets change the plan.
+  'mcpManageEpicEditors': { route: 'mcp/v1/epics/editors', method: 'POST' },
   // E-237 #2382: the epic is the fifth consumer of the grounding engine.
   'mcpGenerateEpicHowItWorks': { route: 'mcp/v1/epics/generate-how-it-works', method: 'POST' },
   'mcpApplyEpicHowItWorks': { route: 'mcp/v1/epics/apply-how-it-works', method: 'POST' },
 
   // Tasks
   'mcpCreateTask': { route: 'mcp/v1/tasks', method: 'POST' },
+  // Claims (E-259 #2747): manage_task action "claim" / "release".
+  'mcpClaimTask': { route: 'mcp/v1/tasks/claim', method: 'POST' },
+  // Suggested edits on someone else's claimed task (E-259 #2809).
+  'mcpTaskSuggestedEdits': { route: 'mcp/v1/tasks/suggested-edits', method: 'POST' },
   'mcpBulkCreateTasks': { route: 'mcp/v1/tasks/bulk', method: 'POST' },
   'mcpUpdateTask': { route: 'mcp/v1/tasks', method: 'PUT' },
   'mcpCompleteTask': { route: 'mcp/v1/tasks/complete', method: 'POST' },

package/handlers/epics.js

@@ -5,35 +5,18 @@
  * Project-First Hierarchy: Epics belong to projects (required),
  * with optional milestone linking.
  *
- * Auto-assignment: When creating epics, automatically applies matching tags
- * based on content analysis against the local project cache.
+ * Tags: only the tagIds the caller passes are applied, in the create request
+ * itself. Keyword matches against the local project cache come back as
+ * `suggestedTags` (see lib/auto-assign.js for why they are not applied).
  */
 
 import { callZephlyAPI } from '../lib/http-client.js';
 import { resolveEpicAutoAssign } from '../lib/auto-assign.js';
+import { suggestTags } from '../lib/suggested-tags.js';
 import { buildEpicUrl } from '../lib/web-url.js';
-import { getLogger } from '../lib/logger.js';
 import { attachLinks } from '../lib/links-at-create.js';
 import { normalizeChangedFiles } from '../lib/changed-files.js';
 
-/**
- * Apply tags to a newly created entity via bulkTagEntities.
- * Non-fatal — logs errors but doesn't throw.
- */
-async function applyAutoTags(organizationId, entityType, entityId, tagIds) {
-  if (!organizationId || !tagIds?.length || !entityId) return;
-  try {
-    await callZephlyAPI('mcpBulkTagEntities', {
-      organizationId,
-      tagIds,
-      entities: [{ entityType, entityId }],
-      operation: 'add',
-    });
-  } catch (err) {
-    getLogger().warn('Auto-tag failed', { entityType, entityId, error: err.message });
-  }
-}
-
 /**
  * Flatten the nested-task result into the fields an agent acts on (#2247).
  *
@@ -79,12 +62,23 @@ export async function manageEpic(args) {
   case 'update': return updateEpic(params);
   case 'generate_how_it_works': return generateEpicHowItWorks(params);
   case 'apply_how_it_works': return applyEpicHowItWorks(params);
+  case 'add_editor': return manageEpicEditor('add', params);
+  case 'remove_editor': return manageEpicEditor('remove', params);
   default: throw new Error(
-    `Unknown action: ${action}. Expected create, update, generate_how_it_works, or apply_how_it_works.`,
+    `Unknown action: ${action}. Expected create, update, generate_how_it_works, apply_how_it_works, ` +
+    'add_editor or remove_editor.',
   );
   }
 }
 
+// Choose who else may change an epic's plan (E-259 #2802). The server decides
+// who may do this; the tool only checks it was asked something answerable.
+async function manageEpicEditor(action, { epicId, editorUserId }) {
+  if (!epicId) throw new Error(`epicId is required to ${action} an editor`);
+  if (!editorUserId) throw new Error(`editorUserId is required to ${action} an editor`);
+  return callZephlyAPI('mcpManageEpicEditors', { epicId, userId: editorUserId, action });
+}
+
 // (Re)generate the epic's grounded, source-attributed "how it works" living
 // description (E-237 #2382). An epic's reality is its tasks — their status,
 // captured decisions and linked commits — and its intent is the epic description
@@ -117,7 +111,7 @@ async function createEpic(args) {
 
   // An epic with its breakdown goes to the composing endpoint (#2247) so the
   // whole thing is one request; without tasks nothing changes. Everything below
-  // this line — auto-tags, links, web URL — acts on the EPIC and so is identical
+  // this line — suggested tags, links, web URL — acts on the EPIC and so is identical
   // either way.
   const result = tasks?.length
     ? await callZephlyAPI('mcpCreateEpicWithTasks', {
@@ -132,18 +126,10 @@ async function createEpic(args) {
 
   if (tasks?.length) summarizeNestedTasks(result);
 
-  // Auto-apply matching tags (non-fatal)
-  const autoAssign = await resolveEpicAutoAssign(title, description);
-  if (autoAssign?.matchedTags?.length && result?.epicId) {
-    await applyAutoTags(
-      autoAssign.organizationId,
-      'epic',
-      result.epicId,
-      autoAssign.matchedTags.map((t) => t.id),
-    );
-    result.autoAssigned = {
-      tags: autoAssign.matchedTags.map((t) => t.name),
-    };
+  // Suggest, never apply, keyword-matched tags (#2830).
+  const suggestedTags = suggestTags(await resolveEpicAutoAssign(title, description), createArgs.tagIds);
+  if (suggestedTags.length && result?.epicId) {
+    result.suggestedTags = suggestedTags;
   }
 
   // Attach create-time links (E-225) — best effort, never fails the create.
@@ -231,6 +217,8 @@ export async function getEpicActivity(args) {
   const params = { epicId: args.epicId };
   if (args.since) params.since = args.since;
   if (args.markSeen === false) params.markSeen = 'false';
+  // Live mode (#2748): the API waits for news, up to its own cap.
+  if (args.waitSeconds > 0) params.waitSeconds = Math.min(Math.floor(args.waitSeconds), 25);
   return callZephlyAPI('mcpGetEpicActivity', params);
 }
 
@@ -258,53 +246,53 @@ export async function managePlanProposal(args = {}) {
   const { action } = args;
 
   switch (action) {
-    case 'propose': {
-      if (!args.epicId) throw new Error('epicId is required to suggest a change');
-      if (!args.plan && !args.ops) {
-        throw new Error('Send the plan you want (or the individual changes) to suggest a change');
-      }
-      return callZephlyAPI('mcpProposePlanChange', {
-        epicId: args.epicId,
-        plan: args.plan,
-        ops: args.ops,
-        title: args.title,
-        rationale: args.rationale,
-      });
+  case 'propose': {
+    if (!args.epicId) throw new Error('epicId is required to suggest a change');
+    if (!args.plan && !args.ops) {
+      throw new Error('Send the plan you want (or the individual changes) to suggest a change');
     }
+    return callZephlyAPI('mcpProposePlanChange', {
+      epicId: args.epicId,
+      plan: args.plan,
+      ops: args.ops,
+      title: args.title,
+      rationale: args.rationale,
+    });
+  }
 
-    case 'list': {
-      if (!args.epicId) throw new Error('epicId is required to list proposals');
-      const params = { epicId: args.epicId };
-      if (args.status) params.status = args.status;
-      return callZephlyAPI('mcpListPlanProposals', params);
-    }
+  case 'list': {
+    if (!args.epicId) throw new Error('epicId is required to list proposals');
+    const params = { epicId: args.epicId };
+    if (args.status) params.status = args.status;
+    return callZephlyAPI('mcpListPlanProposals', params);
+  }
 
-    case 'get': {
-      if (!args.proposalId) throw new Error('proposalId is required');
-      return callZephlyAPI('mcpListPlanProposals', { proposalId: args.proposalId });
-    }
+  case 'get': {
+    if (!args.proposalId) throw new Error('proposalId is required');
+    return callZephlyAPI('mcpListPlanProposals', { proposalId: args.proposalId });
+  }
 
-    case 'review': {
-      if (!args.proposalId) throw new Error('proposalId is required to answer a proposal');
-      if (!args.accept?.length && !args.reject?.length) {
-        throw new Error('Say which changes you are taking (accept) and which you are not (reject)');
-      }
-      return callZephlyAPI('mcpReviewPlanProposal', {
-        proposalId: args.proposalId,
-        accept: args.accept || [],
-        reject: args.reject || [],
-        note: args.note,
-      });
+  case 'review': {
+    if (!args.proposalId) throw new Error('proposalId is required to answer a proposal');
+    if (!args.accept?.length && !args.reject?.length) {
+      throw new Error('Say which changes you are taking (accept) and which you are not (reject)');
     }
+    return callZephlyAPI('mcpReviewPlanProposal', {
+      proposalId: args.proposalId,
+      accept: args.accept || [],
+      reject: args.reject || [],
+      note: args.note,
+    });
+  }
 
-    case 'withdraw': {
-      if (!args.proposalId) throw new Error('proposalId is required to take back a proposal');
-      return callZephlyAPI('mcpReviewPlanProposal', { proposalId: args.proposalId, withdraw: true });
-    }
+  case 'withdraw': {
+    if (!args.proposalId) throw new Error('proposalId is required to take back a proposal');
+    return callZephlyAPI('mcpReviewPlanProposal', { proposalId: args.proposalId, withdraw: true });
+  }
 
-    default:
-      throw new Error(
-        `Unknown action "${action}". Use propose, list, get, review or withdraw.`
-      );
+  default:
+    throw new Error(
+      `Unknown action "${action}". Use propose, list, get, review or withdraw.`
+    );
   }
 }

package/handlers/tasks.js

@@ -7,12 +7,14 @@
  * Code links are derived: the files a task touches (changedFiles / linkedFiles)
  * resolve to the features that own those paths (E-258). Agents name the feature
  * the work advances through `links`.
- * Tags are auto-assigned based on content analysis against the local project cache.
+ * Tags: only the tagIds the caller passes are applied; keyword matches against
+ * the local project cache come back as `suggestedTags` (see lib/auto-assign.js).
  */
 
 import { previewEntityLinks, partitionProposals, attachSuggestionIds } from '../lib/autolink.js';
 import { callZephlyAPI } from '../lib/http-client.js';
 import { resolveTaskAutoAssign } from '../lib/auto-assign.js';
+import { suggestTags } from '../lib/suggested-tags.js';
 import { buildTaskUrl } from '../lib/web-url.js';
 import { getLogger } from '../lib/logger.js';
 import { writeActiveSession, clearActiveSession } from '../lib/active-session.js';
@@ -21,24 +23,6 @@ import { getContext } from './context-manifest.js';
 import { getCommitFiles, getRepositoryRoot } from '../lib/git-helpers.js';
 import { normalizeChangedFiles } from '../lib/changed-files.js';
 
-/**
- * Apply tags to a newly created entity via bulkTagEntities.
- * Non-fatal — logs errors but doesn't throw.
- */
-async function applyAutoTags(organizationId, entityType, entityId, tagIds) {
-  if (!organizationId || !tagIds?.length || !entityId) return;
-  try {
-    await callZephlyAPI('mcpBulkTagEntities', {
-      organizationId,
-      tagIds,
-      entities: [{ entityType, entityId }],
-      operation: 'add',
-    });
-  } catch (err) {
-    getLogger().warn('Auto-tag failed', { entityType, entityId, error: err.message });
-  }
-}
-
 /**
  * Dispatch manage_task actions to the appropriate handler
  */
@@ -54,10 +38,35 @@ export async function manageTask(args) {
   case 'get_commits': return getTaskCommits(params);
   case 'generate_how_it_works': return generateTaskHowItWorks(params);
   case 'apply_how_it_works': return applyTaskHowItWorks(params);
+  case 'claim': return claimTask(params, false);
+  case 'release': return claimTask(params, true);
+  case 'list_suggested_edits': return suggestedEdits(params, false);
+  case 'answer_suggested_edit': return suggestedEdits(params, true);
   default: throw new Error(`Unknown action: ${action}`);
   }
 }
 
+/**
+ * Claim a task, or give it back (E-259 #2747). The server decides who may and
+ * words the answer; a task someone else holds comes back as an error naming
+ * them, which is the agent's cue to pick other work rather than retry.
+ */
+async function claimTask({ taskId, claimNote }, release) {
+  if (!taskId) throw new Error(`taskId is required to ${release ? 'release' : 'claim'} a task`);
+  return callZephlyAPI('mcpClaimTask', release ? { taskId, release: true } : { taskId, note: claimNote });
+}
+
+/**
+ * Suggested edits on a claimed task (E-259 #2809): list what is waiting, or
+ * answer one. The server decides who may accept, reject or withdraw.
+ */
+async function suggestedEdits({ taskId, editId, answer, note }, answering) {
+  if (!taskId) throw new Error('taskId is required');
+  if (!answering) return callZephlyAPI('mcpTaskSuggestedEdits', { taskId });
+  if (!editId || !answer) throw new Error('editId and answer (accept, reject or withdraw) are required');
+  return callZephlyAPI('mcpTaskSuggestedEdits', { taskId, editId, answer, note });
+}
+
 /**
  * Bridge user terminology ("dashboard") to code locations by searching the
  * manifest for the task's own words. Best-effort: returns null when there is
@@ -129,18 +138,13 @@ async function createTask(args) {
     };
   }
 
-  // Auto-apply tags (non-fatal)
-  const autoAssign = await resolveTaskAutoAssign(projectId, title, description);
-  if (autoAssign?.matchedTags?.length && result?.taskId) {
-    await applyAutoTags(
-      autoAssign.organizationId,
-      'task',
-      result.taskId,
-      autoAssign.matchedTags.map((t) => t.id),
-    );
-    result.autoAssigned = {
-      tags: autoAssign.matchedTags.map((t) => t.name),
-    };
+  // Suggest, never apply, keyword-matched tags (#2830).
+  const suggestedTags = suggestTags(
+    await resolveTaskAutoAssign(projectId, title, description),
+    createArgs.tagIds,
+  );
+  if (suggestedTags.length && result?.taskId) {
+    result.suggestedTags = suggestedTags;
   }
 
   if (autoContext) {

package/lib/auto-assign.js

@@ -1,7 +1,13 @@
 /**
  * Auto-assign Utility
- * Matches task/epic content against cached tags for automatic assignment
- * during creation.
+ * Matches task/epic content against cached tags to SUGGEST tags at creation.
+ *
+ * Suggest-only, deliberately (#2830). The matcher fires on any word in the
+ * title or description, so it proposes tags like "notes" or "docs" on work
+ * that merely mentions them. It never actually applied anything before #2830
+ * (the API side was a stub), so applying its output would have switched on a
+ * noisy behaviour nobody had seen. The agent passes the tags it wants as
+ * `tagIds`; matches come back as `suggestedTags` for it to accept.
  */
 
 import { readConfig } from './local-cache.js';

package/lib/create-server.js

@@ -20,6 +20,7 @@ import { listPrompts, getPromptContent } from '../prompts/index.js';
 import { MCP_VERSION } from './version.js';
 import { getLogger } from './logger.js';
 import { isRemoteSafe } from './remote-tools.js';
+import { annotate } from './tool-annotations.js';
 import {
   EMAIL_ALREADY_REGISTERED,
   NOT_AUTHENTICATED,
@@ -84,7 +85,7 @@ export function createServer({ surface = 'local', startSignIn = defaultStartSign
   // cannot disagree. They must agree: filtering only tools/list would leave
   // every excluded handler dispatchable by a client that guesses the name,
   // which is the failure this whole module exists to prevent.
-  const tools = surface === 'remote' ? TOOLS.filter((tool) => isRemoteSafe(tool.name)) : TOOLS;
+  const tools = (surface === 'remote' ? TOOLS.filter((tool) => isRemoteSafe(tool.name)) : TOOLS).map(annotate);
   const available = new Set(tools.map((tool) => tool.name));
 
   const server = new Server(

package/lib/suggested-tags.js

@@ -0,0 +1,21 @@
+/**
+ * Suggested tags (#2830).
+ *
+ * Keyword matches from lib/auto-assign.js are returned to the agent as
+ * `suggestedTags` and never applied; see that file for why.
+ */
+
+/**
+ * Turn keyword matches into the `suggestedTags` a create response carries,
+ * leaving out tags the caller already applied explicitly.
+ *
+ * @param {object|null} autoAssign - Result of resolveTaskAutoAssign / resolveEpicAutoAssign
+ * @param {string[]} [appliedTagIds] - Tag IDs sent with the create
+ * @returns {Array<{id: string, name: string}>}
+ */
+export function suggestTags(autoAssign, appliedTagIds = []) {
+  const applied = new Set(appliedTagIds || []);
+  return (autoAssign?.matchedTags || [])
+    .filter((t) => !applied.has(t.id))
+    .map((t) => ({ id: t.id, name: t.name }));
+}

package/lib/tool-annotations.js

@@ -0,0 +1,104 @@
+/**
+ * MCP tool annotations: which tools only read (#2808).
+ *
+ * Without annotations a client must assume any tool may write or destroy data,
+ * which is what the MCP spec says an unannotated tool means. Claude uses the
+ * hint to sort a connector's tools into read-only and write/delete categories,
+ * so a policy that allows only read-only tools (Claude Team/Enterprise tool
+ * permissions) blocked EVERY tool here, reads included, while
+ * every tool was unannotated.
+ *
+ * A hint, not a control: the API enforces scopes and permissions whatever a
+ * client believes. So the list errs toward leaving a tool OUT. A write wrongly
+ * marked read-only would let it through a read-only policy, while a read left
+ * unmarked only costs the user an approval prompt.
+ *
+ * Membership was verified by tracing each handler to the endpoints it calls
+ * (config/endpoint-map.js): all GETs, or POSTs to query routes the API mounts
+ * behind OptionalReadScopeMiddleware (projects/story, organization/analyze,
+ * graph/*, tags/suggest, links/preview, attachments/download-url). Some have
+ * local side effects that change no EzModo data, and those count as reads:
+ * get_document caches the content into .ezmodo/docs, get_current_project_context
+ * and list_tags cache tags, and detect_git_repository and list_project_worktrees
+ * run read-only git commands.
+ *
+ * Adding a tool? If it only reads, add it here.
+ * __tests__/tool-annotations.test.js fails when a get_/list_/search_ tool is
+ * left unclassified, so a new read cannot silently default to "may write".
+ */
+
+export const READ_ONLY_TOOLS = new Set([
+  'detect_git_repository',
+  'estimate_task',
+  'evaluate_feature_flag',
+  'get_access',
+  'get_ai_insights',
+  'get_attachment_url',
+  'get_catalog',
+  'get_catalog_diff',
+  'get_context',
+  'get_current_project_context',
+  'get_decision',
+  'get_design',
+  'get_design_system',
+  'get_document',
+  'get_document_template',
+  'get_epic',
+  'get_epic_activity',
+  'get_epic_plan',
+  'get_feature',
+  'get_feature_flag',
+  'get_goal',
+  'get_graph',
+  'get_manifest_schema',
+  'get_milestone',
+  'get_org_areas',
+  'get_organization',
+  'get_project',
+  'get_project_changes',
+  'get_project_story',
+  'get_task',
+  'get_testing_summary',
+  'infer_dependencies',
+  'list_agent_suggestions',
+  'list_attachments',
+  'list_catalog_items',
+  'list_catalogs',
+  'list_designs',
+  'list_epic_comments',
+  'list_epics',
+  'list_facts',
+  'list_feature_flags',
+  'list_folders',
+  'list_links',
+  'list_notifications',
+  'list_org_documents',
+  'list_project_worktrees',
+  'list_repositories',
+  'list_tags',
+  'list_test_cases',
+  'list_test_suites',
+  'list_todos',
+  'list_unmapped_paths',
+  'list_watched',
+  'preview_links',
+  'resolve_concepts',
+  'search_epics',
+  'search_features',
+  'search_tasks',
+  'validate_manifest',
+]);
+
+/**
+ * The tool definition as a client should see it: read-only tools carry
+ * `annotations.readOnlyHint: true`; everything else is returned unchanged.
+ * Never mutates the shared definition in tools/.
+ *
+ * @template {{ name: string, annotations?: object }} T
+ * @param {T} tool
+ * @returns {T}
+ */
+export function annotate(tool) {
+  if (!READ_ONLY_TOOLS.has(tool.name)) return tool;
+  return { ...tool, annotations: { ...tool.annotations, readOnlyHint: true } };
+}

package/lib/version.js

@@ -7,4 +7,4 @@
  *
  * Update this when bumping the version in package.json.
  */
-export const MCP_VERSION = '0.19.1';
+export const MCP_VERSION = '0.20.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ezmodo/mcp-server",
-  "version": "0.19.1",
+  "version": "0.20.1",
   "description": "MCP server for ezmodo - AI-first project management",
   "main": "index.js",
   "type": "module",

package/tools/epics.js

@@ -44,7 +44,8 @@ export const EPIC_TOOLS = [
       'IMPORTANT when creating: Call get_context first for each area the epic covers to discover relevant ' +
       'files and integration points. Include in the description which layers/services are affected and ' +
       'reference specific file paths. Create child tasks that each reference specific files from context queries. ' +
-      'Auto-applies matching tags from cached project context based on content analysis. ' +
+      'Tags: pass the tag IDs you want as tagIds; the response lists keyword-matched tags you did not pass as ' +
+      'suggestedTags, which are NOT applied — add any that fit with an update. ' +
       'To align an epic to an organization goal, link it to a milestone that is linked to that goal ' +
       '(set milestoneId) — epics have no direct goal field. ' +
       'BREAKING DOWN A FEATURE: pass the child tasks in the `tasks` array on create and the epic and its ' +
@@ -56,8 +57,12 @@ export const EPIC_TOOLS = [
       properties: {
         action: {
           type: 'string',
-          enum: ['create', 'update', 'generate_how_it_works', 'apply_how_it_works'],
-          description: 'Action to perform. "generate_how_it_works" (re)generates the epic\'s grounded, ' +
+          enum: ['create', 'update', 'generate_how_it_works', 'apply_how_it_works', 'add_editor', 'remove_editor'],
+          description: 'Action to perform. "add_editor" / "remove_editor" (epicId + editorUserId) choose who ' +
+            'else may change the epic\'s plan, decide its questions and answer suggested changes (E-259). ' +
+            'Only the owner, the creator or an org admin may choose; an editor may remove themselves. ' +
+            'get_epic lists the current editors. ' +
+            '"generate_how_it_works" (re)generates the epic\'s grounded, ' +
             'source-attributed "how it works" living description from its reality — its tasks\' status ' +
             'rollup, their captured decisions and their linked commits (requires epicId; AI-quota gated). ' +
             'An epic is where intent and reality drift furthest apart: intent is a charter written once, ' +
@@ -68,7 +73,12 @@ export const EPIC_TOOLS = [
         // --- Identifiers ---
         epicId: {
           type: 'string',
-          description: 'Epic ID (required for update, generate_how_it_works, apply_how_it_works)',
+          description: 'Epic ID (required for update, generate_how_it_works, apply_how_it_works, ' +
+            'add_editor, remove_editor)',
+        },
+        editorUserId: {
+          type: 'string',
+          description: 'add_editor / remove_editor: the user to add or remove (must be in the organization)',
         },
         markdown: {
           type: 'string',
@@ -137,10 +147,11 @@ export const EPIC_TOOLS = [
             name: { type: 'string' },
           },
         },
-        labels: {
+        tagIds: {
           type: 'array',
           items: { type: 'string' },
-          description: 'Array of label names',
+          description: 'Tag IDs for categorization (get them from get_current_project_context). ' +
+            'Used by create and update; on update this REPLACES the set.',
         },
         color: {
           type: 'string',
@@ -255,7 +266,8 @@ export const EPIC_TOOLS = [
       'Responses include `descriptionDocumentId` — the id of the backing rich-description Document ' +
       'when the description has been promoted to one (E-189), otherwise omitted. ' +
       'Responses also include `derivedGoalIds` — the organization goal(s) this epic aligns to, ' +
-      'derived via its milestone (epics have no direct goal field).',
+      'derived via its milestone (epics have no direct goal field). ' +
+      '`editors` lists the people besides the owner who may change its plan (E-259).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -390,12 +402,18 @@ export const EPIC_TOOLS = [
     name: 'get_epic_activity',
     description: 'Catch me up on an epic (E-259): what changed since YOU last looked. Returns `summary`, ' +
       'plain sentences you can relay to your person as-is, most important first: decisions waiting on ' +
-      'their view, comments that mention or reply to them, decisions made, new plan versions (who ' +
+      'their view, open questions put to them and open objections, comments that mention or reply to ' +
+      'them, decisions made, new plan versions (who ' +
       'changed what, and which AI did it for them), and tasks added, started, finished or blocked. ' +
       'The details are alongside. Their own changes are left out. Call it when you start or resume ' +
       'work on an epic other people also work on, and before changing its plan. By default this also ' +
       'marks the epic as caught up, so the next call shows only newer changes; pass markSeen:false to ' +
-      'look without that.',
+      'look without that.\n\n' +
+      'LIVE: pass waitSeconds (up to 25) to wait for something to happen instead of hearing ' +
+      '"nothing has changed" — the call returns as soon as someone changes the plan, comments, ' +
+      'decides, or picks up or moves a task. Call it again to keep following a shared session. ' +
+      '`hereNow` says who else is on the epic right now, people and their AIs; calling any epic tool ' +
+      'shows you there too.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -409,6 +427,10 @@ export const EPIC_TOOLS = [
           type: 'boolean',
           description: 'Mark the epic as caught up after answering (default true)',
         },
+        waitSeconds: {
+          type: 'number',
+          description: 'Wait up to this many seconds (max 25) for something new before answering',
+        },
       },
       required: ['epicId'],
     },
@@ -417,12 +439,15 @@ export const EPIC_TOOLS = [
     name: 'list_epic_comments',
     description: 'Read an epic\'s discussion (E-259), oldest first. Each comment says who wrote it and, ' +
       'when an AI wrote it for them, which AI (`agentName`). Replies carry `parentId`. ' +
-      'Read this before planning or changing a shared epic: other people\'s questions and objections live here.',
+      'Read this before planning or changing a shared epic: other people\'s questions and objections live here. ' +
+      'Each comment has a `kind` (comment, question, objection, alternative); the last three stay open until ' +
+      '`resolvedAt` is set. Pass open:true for only the ones still waiting — check it before approving a plan.',
     inputSchema: {
       type: 'object',
       properties: {
         epicId: { type: 'string', description: 'The epic ID (required)' },
         limit: { type: 'number', description: 'Maximum comments to return (default 100, max 500)' },
+        open: { type: 'boolean', description: 'Only the questions, objections and alternatives not yet settled' },
       },
       required: ['epicId'],
     },
@@ -432,7 +457,11 @@ export const EPIC_TOOLS = [
     description: 'Post to an epic\'s discussion (E-259), or reply to a comment with `parentId`. ' +
       'Posted as the person whose key you use, marked as written by you. ' +
       'Mentioned people, the author you reply to and everyone following the epic are notified, ' +
-      'and posting makes that person follow it. Write plainly: one point per comment, readable by anyone.',
+      'and posting makes that person follow it. Write plainly: one point per comment, readable by anyone.\n\n' +
+      'Say what the comment is with `kind`: a `question` you need answered, an `objection` to the plan, or ' +
+      'an `alternative` approach. Those stay open until settled, show up in catch me up, and an open objection ' +
+      'warns whoever approves the plan. To answer one, reply with parentId and resolvesParent:true ' +
+      '(the person who raised it, or the epic\'s owner, may settle it; anyone may reply).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -440,6 +469,15 @@ export const EPIC_TOOLS = [
         content: { type: 'string', description: 'The comment (markdown)' },
         parentId: { type: 'string', description: 'Reply to this comment' },
         mentions: { type: 'array', items: { type: 'string' }, description: 'User IDs to notify' },
+        kind: {
+          type: 'string',
+          enum: ['comment', 'question', 'objection', 'alternative'],
+          description: 'What this is (default comment). Replies are always comments.',
+        },
+        resolvesParent: {
+          type: 'boolean',
+          description: 'With parentId: this reply settles the question, objection or alternative it answers',
+        },
       },
       required: ['epicId', 'content'],
     },
@@ -453,7 +491,7 @@ export const EPIC_TOOLS = [
       'take some and leave others. Nothing changes until they do.\n' +
       'list: what is waiting on an epic. Open ones come first, and each change that no longer fits the ' +
       'current plan is flagged with the reason.\n' +
-      'review (owner, creator or org admin only): `accept` and `reject` name changes by their op id. ' +
+      'review (owner, editors, creator or org admin only): `accept` and `reject` name changes by their op id. ' +
       'A change you name in neither is left for later and the proposal stays open. A change whose task ' +
       'someone has since removed is reported back as stale rather than quietly reapplied.\n' +
       'withdraw: take back a proposal you made.',

package/tools/tasks.js

@@ -32,14 +32,51 @@ export const TASK_TOOLS = [
       properties: {
         action: {
           type: 'string',
-          enum: ['create', 'update', 'complete', 'defer', 'link_commit', 'unlink_commit', 'get_commits', 'generate_how_it_works', 'apply_how_it_works'],
-          description: 'Action to perform. "generate_how_it_works" (re)generates the task\'s ' +
+          enum: [
+            'create', 'update', 'complete', 'defer', 'link_commit', 'unlink_commit', 'get_commits',
+            'generate_how_it_works', 'apply_how_it_works', 'claim', 'release',
+            'list_suggested_edits', 'answer_suggested_edit',
+          ],
+          description: 'Action to perform. "claim" (taskId, optional claimNote) says you are working on ' +
+            'this task, so other people\'s AIs on the same epic pick different work (E-259). Claim ' +
+            'BEFORE starting a task on a shared epic. It lasts 2 hours and renews while you update ' +
+            'the task or link commits; claiming again renews it. If someone else holds it you are ' +
+            'told who and which branch their work is on — pick another task. The answer warns about ' +
+            'other in-progress tasks on the epic that touch the same files, with the branch each is on, ' +
+            'so you can build on that work or keep clear of it. "release" gives it back when you stop. ' +
+            'TASK RULES: on a task someone ELSE has claimed, changing its title, description, steps or ' +
+            'epic, or deleting it, is sent to them as a suggested edit (the response says ' +
+            '`suggested: true`; anything else in the same update still applies), and changing its ' +
+            'status, assignee or step progress is refused — leave a comment instead. The claimer and ' +
+            'whoever runs the epic are not limited. "list_suggested_edits" (taskId) shows what is ' +
+            'waiting on a task; "answer_suggested_edit" (taskId, editId, answer: accept|reject|withdraw, ' +
+            'optional note) answers one — the claimer or whoever runs the epic accepts or rejects, the ' +
+            'author withdraws. ' +
+            '"generate_how_it_works" (re)generates the task\'s ' +
             'grounded, source-attributed "how it works" living description from its reality — ' +
             'subtasks, comments, status history, commits plus a manifest pass over linked files ' +
             '(requires taskId; AI-quota gated). "apply_how_it_works" (BYO-AI) persists a summary ' +
             'YOU authored: pass markdown + sources; the server validates your cited sources against ' +
             'the real grounded context (dropping fabricated ones) before saving — no server model call.',
         },
+        editId: {
+          type: 'string',
+          description: 'answer_suggested_edit: the suggested edit to answer',
+        },
+        answer: {
+          type: 'string',
+          enum: ['accept', 'reject', 'withdraw'],
+          description: 'answer_suggested_edit: accept or reject it (the claimer or whoever runs the epic), ' +
+            'or withdraw your own',
+        },
+        note: {
+          type: 'string',
+          description: 'answer_suggested_edit: what you want to say back, optional',
+        },
+        claimNote: {
+          type: 'string',
+          description: 'claim: what you are about to do, in a few words (shown to the others)',
+        },
         // --- Identifiers (used by most actions) ---
         taskId: {
           type: 'string',